docguard-guard
Run DocGuard guard validation against Canonical-Driven Development standards. Parses output, triages severity, suggests targeted fixes, and optionally chains to docguard-fix for automated remediation.
SKILL.md.specify/extensions/docguard/skills/docguard-guard/SKILL.md
GitHub<!-- docguard:version: 0.9.9 -->
DocGuard Guard Skill
User Input
$ARGUMENTS
You MUST consider the user input before proceeding (if not empty).
Goal
Execute DocGuard's 19-validator guard suite against the current project, parse structured results, triage findings by severity and impact, and produce an actionable remediation plan. This skill transforms raw CLI output into an AI-digestible quality assessment.
Pre-Execution Checks
Verify DocGuard is available:
- Check if
npx docguard-cli --versionsucceeds - If not available, check if
node cli/docguard.mjs --helpexists (local dev mode) - If neither works: ERROR "DocGuard CLI not found. Install with: npm i -g docguard-cli"
- Check if
Detect project root:
- Look for
.docguard.json,docs-canonical/, orCHANGELOG.mdas project markers - If none found: ERROR "No CDD project detected. Run
docguard initfirst."
- Look for
Execution Flow
Step 1: Run Guard with Machine-Readable Output
Execute the guard command and capture full output:
npx docguard-cli guard 2>&1
If in a DocGuard development environment (cli/docguard.mjs exists), use:
node cli/docguard.mjs guard 2>&1
Step 2: Parse Validator Results
Extract from guard output each validator's status. Build an internal results table:
| Validator | Priority | Checks Passed | Total Checks | Status |
|---|---|---|---|---|
| Structure | HIGH | N | M | ✅/⚠️/❌ |
| Doc Sections | HIGH | N | M | ✅/⚠️/❌ |
| ... | ... | ... | ... | ... |
Status mapping:
✅= All checks passed⚠️= Warning (non-blocking, but should fix)❌= Failure (blocking — must fix before commit)
Step 3: Severity Triage
Classify every non-passing check using this priority matrix:
CRITICAL (fix immediately):
- Structure failures (missing canonical docs)
- Security failures (hardcoded secrets, missing SECURITY.md)
- Test-Spec failures (tests don't match spec)
HIGH (fix before commit):
- Doc Sections failures (missing required sections)
- Drift detection (undocumented code deviations)
- Changelog gaps
- Traceability breaks
MEDIUM (fix this sprint):
- Freshness warnings (stale docs)
- Docs-Coverage gaps (undocumented config files)
- Doc-Quality issues (readability, negation language)
- Metrics-Consistency mismatches
LOW (fix when convenient):
- TODO-Tracking items
- Schema-Sync gaps
- Metadata-Sync minor mismatches
- Spec-Kit warnings (spec structure gaps)
Step 4: Generate Triage Report
Output a structured markdown report:
## DocGuard Guard Report
**Score**: [X]/[Y] checks passed ([percentage]%)
**Overall Status**: ✅ PASS | ⚠️ WARN | ❌ FAIL
### Summary by Priority
| Priority | Count | Validators Affected |
|----------|-------|-------------------|
| CRITICAL | N | [list] |
| HIGH | N | [list] |
| MEDIUM | N | [list] |
| LOW | N | [list] |
### Findings
#### CRITICAL
1. [Validator]: [Specific issue] → **Fix**: [Exact action to take]
#### HIGH
1. [Validator]: [Specific issue] → **Fix**: [Exact action to take]
[... continue for MEDIUM/LOW only if user requests or total findings < 10]
Step 5: Remediation Recommendations
For each finding, provide a specific, actionable fix — not "fix the issue" but the exact file, section, and content to change:
- Missing file: "Create
docs-canonical/SECURITY.mdwith metadata header and these sections: [list]" - Missing section: "Add
## Threat Modelsection todocs-canonical/SECURITY.mdafter line N" - Stale doc: "Update
<!-- docguard:last-reviewed YYYY-MM-DD -->in [file] to today's date" - Negation language: "Replace 'Never store secrets in...' with 'Store secrets exclusively in...'"
- Undocumented config: "Add
.venvdocumentation todocs-canonical/ARCHITECTURE.mdunder Developer Tools"
Step 6: Offer Next Actions
Based on the triage results:
- If all PASS: "All 19 validators passed. Project is CDD-compliant. Ready to commit."
- If only MEDIUM/LOW warnings: "Non-blocking warnings found. Safe to commit, but consider running
/docguard.fixfor automated remediation." - If HIGH or CRITICAL failures: "Blocking issues found. Fix these before committing. Suggest running
/docguard.fix --doc [most impactful doc]next."
Present the user with options:
- "Fix all automatically" → Suggest:
/docguard.fix - "Fix specific doc" → Suggest:
/docguard.fix --doc [name] - "Ignore warnings and proceed" → Warn about CDD compliance gap
Behavior Rules
- ALWAYS run the actual CLI — never simulate or guess guard results
- Parse real output — don't hallucinate check counts or validator names
- Be specific — every fix recommendation must reference an actual file path
- Respect severity — don't escalate LOW to CRITICAL or vice versa
- Track progress — if user runs guard multiple times, compare before/after
- If user provides
$ARGUMENTSlike "just structure" or "only security", filter report to those validators
Integration with Spec Kit (Extension-First)
DocGuard is a spec-kit extension. When this project has a .specify/ directory:
- Read
.specify/memory/constitution.mdfor project principles that constrain documentation - Include Spec-Kit validator results in the triage
- Cross-reference spec quality issues with
specs/*/spec.mdfile paths - When specification issues found → suggest
/speckit.specifyor/speckit.clarify - When architecture gaps found → suggest
/speckit.plan - When cross-artifact inconsistencies exceed 3 → suggest
/speckit.analyze - When no constitution exists → suggest
/speckit.constitutionas first step
Context
$ARGUMENTS