docguard-review

name	docguard-review
description	Cross-document consistency analysis and quality assessment. Performs read-only analysis across all canonical docs, identifies drift, coverage gaps, and quality issues. Produces a structured report with severity-ranked findings. Modeled after speckit-analyze.
compatibility	Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
metadata	{"author":"docguard","version":"0.33.1","source":"extensions/spec-kit-docguard/skills/docguard-review"}

DocGuard Review Skill

User Input

$ARGUMENTS

You MUST consider the user input before proceeding (if not empty).

Goal

Perform a comprehensive, read-only analysis of the project's documentation health. Unlike /docguard.guard (which runs CLI validators), this skill performs semantic analysis — checking whether documentation actually matches the codebase, whether cross-references are consistent, and whether the documentation tells a coherent story.

Operating Constraints

STRICTLY READ-ONLY: Do not modify any files. Output a structured analysis report only. Offer remediation suggestions that the user must explicitly approve before any changes are made.

Execution Flow

Step 1: Gather Documentation Inventory

1. List all canonical docs: Read every file in docs-canonical/
2. List support files: Check for CHANGELOG.md, DRIFT-LOG.md, AGENTS.md, README.md, ROADMAP.md
3. Check for spec-kit artifacts: If .specify/ exists, include specs/*/spec.md, specs/*/plan.md, specs/*/tasks.md
4. Build a document map:

Document	Exists	Last Modified	Size	Metadata Version
ARCHITECTURE.md	✅	2026-03-14	5.2KB	0.5.0
SECURITY.md	✅	2026-03-14	3.1KB	0.5.0
...	...	...	...	...

Step 2: Run Quantitative Analysis

Execute DocGuard's diagnostic and scoring tools:

npx docguard-cli diagnose 2>&1
npx docguard-cli score 2>&1
npx docguard-cli guard 2>&1

Record:

• Guard pass/fail counts per validator
• CDD maturity score (0-100)
• ALCOA+ compliance attributes
• Category breakdown

Step 3: Semantic Cross-Document Analysis

This is the unique value of the review skill — analysis that CLI validators cannot do.

A. Terminology Consistency

• Extract key technical terms from each document
• Flag terms used differently across documents (e.g., "validator" vs "checker" vs "rule")
• Flag abbreviations used without definition
• Build a de facto glossary

B. Architecture ↔ Code Alignment

• Read ARCHITECTURE.md component list
• Verify each listed component actually exists as a directory/module
• Flag components that exist in code but are missing from ARCHITECTURE.md
• Flag components listed in ARCHITECTURE.md that don't exist in code

C. Data Model ↔ Code Alignment

• Read DATA-MODEL.md schemas/structures
• Search codebase for actual data structures
• Flag schemas documented but not implemented
• Flag schemas implemented but not documented

D. Test Coverage ↔ Test-Spec Alignment

• Read TEST-SPEC.md critical flows
• Check actual test files exist for each critical flow
• Flag test scenarios documented but not implemented
• Flag test files with no corresponding TEST-SPEC.md entry

E. Security Claims ↔ Implementation

• Read SECURITY.md auth/secrets claims
• Verify auth implementation exists in code
• Check that listed secrets are actually used
• Flag security-relevant code not mentioned in SECURITY.md

F. Cross-Reference Integrity

• Find all internal doc links ([text](file) and See ARCHITECTURE.md)
• Verify every referenced file/section actually exists
• Flag broken cross-references
• Flag orphaned sections not referenced anywhere

Step 4: Quality Assessment

For each document, evaluate:

Criterion	Weight	Score	Notes
Completeness	30%	0-10	Are all mandatory sections present?
Accuracy	30%	0-10	Does content match actual codebase?
Clarity	20%	0-10	Readability, specificity, no jargon
Currency	10%	0-10	Is content up-to-date with latest code?
Cross-refs	10%	0-10	Are references valid and bidirectional?

Step 5: Severity Classification

Classify every finding using this matrix:

• CRITICAL: Security claim doesn't match implementation, missing mandatory doc, broken architecture reference
• HIGH: Undocumented component, stale content (>5 commits behind), terminology conflict
• MEDIUM: Missing cross-reference, minor coverage gap, readability issue
• LOW: Formatting inconsistency, optional section missing, minor terminology drift

Step 6: Produce Analysis Report

Output a structured markdown report (do NOT write to disk):

## DocGuard Documentation Review

### Executive Summary
- **Overall Health**: [A+/A/B/C/D/F] ([score]/100)
- **Documents Analyzed**: [N]
- **Findings**: [CRITICAL: N, HIGH: N, MEDIUM: N, LOW: N]
- **Top Risk**: [Most impactful finding]

### Findings Table

| ID | Category | Severity | Location | Summary | Recommendation |
|----|----------|----------|----------|---------|----------------|
| R01 | Terminology | HIGH | ARCH:L15, SEC:L22 | "validator" vs "checker" | Standardize on "validator" |
| R02 | Coverage | MEDIUM | DATA-MODEL.md | Schema X undocumented | Add Schema X to Data Model |

### Per-Document Health

| Document | Completeness | Accuracy | Clarity | Currency | Cross-refs | Overall |
|----------|:----------:|:-------:|:------:|:-------:|:----------:|:-------:|
| ARCHITECTURE.md | 9/10 | 8/10 | 9/10 | 7/10 | 10/10 | 8.8/10 |
| SECURITY.md | 8/10 | 9/10 | 8/10 | 9/10 | 7/10 | 8.4/10 |

### Semantic Consistency
- **Terminology conflicts**: [N found]
- **Architecture gaps**: [N components undocumented]
- **Broken cross-refs**: [N found]
- **Test coverage gaps**: [N critical flows untested]

### Recommendations (Priority Order)
1. [Most impactful fix] — estimated effort: [LOW/MEDIUM/HIGH]
2. [Second most impactful] — estimated effort: [LOW/MEDIUM/HIGH]
3. ...

Step 7: Offer Next Actions

Based on findings:

• If CRITICAL issues: "Run /docguard.fix --doc [name] to resolve blocking issues"
• If spec-related gaps: "Run /speckit.specify to update specifications" or "/speckit.clarify to resolve ambiguities"
• If architecture drift: "Run /speckit.plan to realign implementation plan with codebase"
• If only LOW/MEDIUM: "Documentation is healthy. Consider /docguard.fix for polish"
• If constitution missing: "Run /speckit.constitution to establish project principles"
• If all clean: "Documentation is excellent. No action needed."

Ask: "Would you like me to fix the top N issues? (I'll show you what I plan to change before applying)"

Behavior Rules

• NEVER modify files — this is strictly read-only analysis
• ALWAYS run real CLI commands — don't simulate or guess results
• Be specific — cite exact file paths, line numbers, and content
• Compare actual code vs docs — don't just validate formatting
• Limit findings to 50 — aggregate overflow in a summary count
• Prioritize high-signal findings — one CRITICAL finding is worth ten LOW findings

Context

$ARGUMENTS