What do the PASS/WARN/FAIL statuses mean?

PASS means all six checks passed; WARN indicates minor gaps; FAIL flags major issues to address before sharing.

Can I customize thresholds for the checks?

The six checks are defined for consistency; thresholds (e.g., artifact counts or test coverage) can be guided by doc size but should remain aligned with quality goals.

How do I fix broken cross-references?

Verify that referenced files and types exist, update links or definitions as needed, and re-run the gate to confirm fixes.

vibe-doc-quality-gate

npx machina-cli add skill ash1794/vibe-engineering/doc-quality-gate --openclaw

Files (1)

SKILL.md

2.6 KB

vibe-doc-quality-gate

A fast quality gate for technical documents. Not a deep review — just catches the obvious structural issues.

When to Use This Skill

After creating or editing a specification document
After writing a design doc or technical RFC
Before sharing a document for review
Periodic document health checks

When NOT to Use This Skill

For code review (use vibe-quality-loop or vibe-devil-advocate-review)
For informal notes or scratch documents
For README files that are just getting started

The 6 Checks

1. Overview/Quick Start

Does the document have an overview or quick-start section that explains what this is and why it matters in <5 paragraphs?

PASS: Overview exists with purpose and scope
FAIL: No overview, or jumps straight into details

2. Structural Completeness

Does the document reference concrete artifacts?

At least 3 file paths or API endpoints
At least 1 data structure or type definition
At least 1 error case or failure mode
At least 3 test cases or validation steps
PASS: All present | WARN: 2-3 present | FAIL: 0-1 present

3. Cross-Reference Integrity

Are references to other documents, APIs, or code valid?

Check that referenced files exist
Check that referenced types/functions exist
PASS: All references valid | FAIL: Broken references found

4. Test Coverage

Does the document specify how to verify the implementation?

At least 3 test cases for small docs
At least 10 for large docs
PASS: Adequate test coverage | WARN: Below threshold

5. Command Accuracy

Are commands, paths, and code snippets accurate?

Do file paths exist (or are marked "to be created")?
Do commands actually run?
PASS: All verified | FAIL: Broken commands/paths

6. Self-Sufficiency

Could someone implement this without asking questions?

Pick 3 random sections. Could you implement each without external context?
PASS: Yes | FAIL: Ambiguous or incomplete sections

Output Format

Document Quality Gate: [Document Name]

Overall: PASS / WARN / FAIL

Check	Status	Notes
1. Overview	✓/✗	[notes]
2. Structure	✓/◐/✗	[X/4 artifacts]
3. Cross-refs	✓/✗	[X broken]
4. Tests	✓/◐	[X cases]
5. Commands	✓/✗	[X broken]
6. Self-sufficiency	✓/✗	[notes]

Issues to Fix

[Specific issue with location]

Source

git clone https://github.com/ash1794/vibe-engineering/blob/master/skills/doc-quality-gate/SKILL.mdView on GitHub

Overview

vibe-doc-quality-gate provides a quick, structural check for technical docs like specs, design docs, and RFCs. It’s not a deep review but catches obvious gaps before a document is shared. Use it after editing or drafting to improve clarity, completeness, and readiness for review.

How This Skill Works

It runs a six-check framework covering overview, structure, cross-references, test coverage, command accuracy, and self-sufficiency. Each check looks for concrete artifacts, valid references, runnable commands, and sufficient test-like validation. Results appear as PASS/WARN/FAIL with notes to guide fixes.

When to Use It

After creating or editing a specification document
After writing a design doc or technical RFC
Before sharing a document for review
Periodic document health checks
When updating an existing doc to ensure changes stay valid

Quick Start

Step 1: Run vibe-doc-quality-gate on the edited document
Step 2: Review the PASS/WARN/FAIL status and fix highlighted issues
Step 3: Re-run until status is PASS or clearly manageable WARN with notes

Best Practices

Ensure an Overview/Quick Start exists that explains purpose and scope
Include concrete artifacts: at least 3 file paths or API endpoints, 1 data structure, 1 error case, and 3+ test/validation steps
Check all cross-references exist and are valid
Provide clear test coverage thresholds scaled to doc size
Verify commands and file paths are accurate or clearly marked as to be created

Example Use Cases

Spec: API v3 for payments with file paths like /api/payments, schema definitions, and test suites
Design doc: Event-driven microservice with data structures and endpoints
RFC: Authentication flow across services and token semantics
Public API reference draft with cross-links and endpoint descriptions
Migration RFC for database schema with rollback steps and verifications

Frequently Asked Questions

Add this skill to your agents