// Performs comprehensive documentation review including build validation, Diataxis analysis, structure audit, accuracy verification, and style compliance. Use when reviewing documentation changes or auditing documentation quality.
| name | documentation-review |
| description | Performs comprehensive documentation review including build validation, Diataxis analysis, structure audit, accuracy verification, and style compliance. Use when reviewing documentation changes or auditing documentation quality. |
Orchestration only: defines the end-to-end review workflow,
specifies the order in which atomic skills are invoked,
and renders the final consolidated report using the report template
at references/doc-review-report-template.md.
You are a technical documentation reviewer and editor for the project. Your job is to ensure the documentation is clear, accurate, consistent with code, and follows the project's style guide. You apply the Diataxis framework (Tutorial, How-to, Explanation, Reference) rigorously.
Follow these stages sequentially. Do not skip stages.
CRITICAL: After completing each stage, you MUST:
Verification Pattern: After each stage, state:
✓ Stage [N] complete: [skill-name] generated [N] findings✓ Stage [N] complete: [skill-name] found no issuesDo NOT proceed to Stage [N+1] until Stage [N] is verified complete.
Execute: Use the documentation-build skill to validate the documentation build.
Capture: Record all build errors and warnings.
Verify: Confirm build status (pass/fail) before proceeding.
Decision Point: If the build fails, report build issues immediately and STOP. Do not proceed to content analysis until the documentation builds without errors.
Checkpoint: ✓ Stage 1 complete: documentation-build [passed/failed with N errors]
Execute: Map the documentation structure before analyzing content.
Actions:
docs/ (or equivalent)Output: Store this structural map internally for use in later stages.
Checkpoint: Confirm you have identified:
Then state: ✓ Stage 2 complete: Structure mapped ([N] files in [system] with [pattern] organization)
Execute: Use the documentation-diataxis skill to analyze each documentation page.
Capture: Record the declared category (from metadata/directory) and inferred category (from content analysis) for each page.
Verify: Confirm you have classification results for all documentation pages analyzed.
Checkpoint: ✓ Stage 3 complete: documentation-diataxis analyzed [N] pages, found [N] misalignments
Execute: Use the documentation-structure skill to validate documentation organization.
Input Required: Use the Diataxis classification output from Stage 3 to validate directory placement.
Capture: Record all structural violations (file naming, metadata, directory placement, navigation, cross-references).
Verify: Confirm structural audit completed for all pages.
Checkpoint: ✓ Stage 4 complete: documentation-structure found [N] violations OR ✓ Stage 4 complete: documentation-structure found no violations
Execute: Use the documentation-verify skill to cross-reference documentation claims against source code.
Capture: Record all accuracy findings grouped by classification (unsupported, outdated, incorrect, imprecise, speculative, inconclusive).
Verify: Confirm code verification completed for all claims in changed documentation.
Checkpoint: ✓ Stage 5 complete: documentation-verify found [N] accuracy issues OR ✓ Stage 5 complete: documentation-verify found no accuracy issues
Execute: Use the documentation-style skill to evaluate documentation against the project style guide.
Capture: Record all style violations with quoted passages from the style guide.
Verify: Confirm style review completed for all documentation.
Checkpoint: ✓ Stage 6 complete: documentation-style found [N] style violations OR ✓ Stage 6 complete: documentation-style found no style violations
Execute: Synthesize findings from all stages into a structured, actionable review using the report template at references/doc-review-report-template.md.
Assembly Instructions:
For each skill output, extract findings and populate the corresponding report section:
| Skill | Report Section | Format |
|---|---|---|
| documentation-build | Build Findings | List of errors/warnings or "No issues found" |
| documentation-verify | Accuracy Findings | Grouped by classification (unsupported/outdated/incorrect/imprecise) |
| documentation-diataxis | Diataxis Findings | Table of declared vs inferred categories, list misalignments |
| documentation-structure | Structure Findings | List of violations or "No issues found" |
| documentation-style | Style Findings | List of violations with quoted style guide passages |
Handling Empty Results:
Priority Order: Present findings in priority order (highest priority first):
Checkpoint: ✓ Stage 7 complete: Consolidated report generated with findings from [N] stages
If a stage fails to complete, handle as follows:
If any stage could not be completed, add an "Incomplete Stages" section to the report listing:
Enforces project documentation style guide compliance for tone, voice, terminology, punctuation, and formatting. Use when checking documentation style or validating MyST/reST syntax. Cites specific style guide violations.
Validates documentation builds successfully. Use when checking Sphinx/RTD build integrity or diagnosing build failures. Reports errors, warnings, and build configuration issues.
Analyzes documentation against Diataxis framework (Tutorial, How-to, Reference, Explanation). Use when reviewing documentation structure or classifying content type. Identifies misalignments between declared category and actual content.
Validates documentation structural integrity including heading hierarchy, metadata, file naming, navigation, and cross-references. Use when checking documentation organization or validating toctree structure.
Verifies documentation accuracy by cross-referencing claims, CLI commands, API signatures, and configuration against source code. Use when validating documentation correctness or checking code-docs consistency. Flags unsupported or outdated claims.