# Documentation Review

> 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.

- Skill: `canonical/documentation-review` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add canonical/documentation-review`
- Raw SKILL.md: https://api.skillmd.com/api/skills/canonical/documentation-review/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: canonical (https://skillmd.com/u/canonical)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/canonical/documentation-review

---


# Documentation Review

## Scope

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`.
This orchestration must support docs-only repositories where documentation content and documentation tooling are the primary verification scope.

## Persona

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.

## Workflow

Follow these stages sequentially. **Do not skip stages.**

### Execution Requirements

**CRITICAL:** After completing each stage, you MUST:
1. Confirm the skill was actually invoked (not just described)
2. Capture the output and record findings
3. State the completion status explicitly

**Verification Pattern:**
After each stage, state:
- `✓ Stage [N] complete: [skill-name] generated [N] findings`
- If no findings: `✓ Stage [N] complete: [skill-name] found no issues`

**Do NOT proceed to Stage [N+1] until Stage [N] is verified complete.**

---

### Stage 1: Build Validation

**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]`

---

### Stage 2: Documentation Structure Discovery

**Execute:** Map the documentation structure before analyzing content.

**Actions:**
1. Detect and list all documentation files under the docs root (`docs/` first; use repository root only when `conf.py` and `Makefile` are at repository root, otherwise use `docs/` or equivalent).
2. Identify the documentation build system (Sphinx, MkDocs, Jekyll, etc.)
3. Note the directory structure (flat vs. categorized)
4. Record any metadata patterns (frontmatter, sidebar configs)

**Output:** Store this structural map internally for use in later stages.

**Checkpoint:** Confirm you have identified:
- [ ] Documentation root directory
- [ ] Build system type
- [ ] File organization pattern
- [ ] Metadata conventions (if any)

Then state: `✓ Stage 2 complete: Structure mapped ([N] files in [system] with [pattern] organization)`

---

### Stage 3: Diataxis Classification

**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`

---

### Stage 4: Structure Audit

**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`

---

### Stage 5: Accuracy Verification

**Execute:** Use the `documentation-verify` skill to cross-reference documentation claims against repository evidence.

For docs-only repositories, validate claims against documentation tooling and artifacts in the same repository (for example, `conf.py`, `Makefile`, Sphinx configuration, redirects, and documentation examples).

**Capture:** Record all accuracy findings grouped by classification (unsupported, outdated, incorrect, imprecise, speculative, inconclusive).

**Verify:** Confirm repository-evidence 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`

---

### Stage 6: Style Review

**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`

---

### Stage 7: Consolidated Report

**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:**
- If a skill produces no findings: Write "No issues found" in that section
- If a skill is not applicable: Write "Not applicable - [reason]" (e.g., "Not applicable -- Sphinx artifacts not detected")

**Priority Order:** Present findings in priority order (highest priority first):

1. **Build Findings (BLOCKING)** - Must be resolved before content analysis
2. **Accuracy Findings (CRITICAL)** - Code-documentation mismatches
3. **Diataxis Findings (HIGH)** - Category misalignments affecting usability
4. **Structure Findings (MEDIUM)** - Organizational and navigation issues
5. **Style Findings (LOW)** - Style guide compliance

**Checkpoint:** `✓ Stage 7 complete: Consolidated report generated with findings from [N] stages`

---

## Error Handling

If a stage fails to complete, handle as follows:

### Build Validation Failure
- Report build errors immediately
- STOP the workflow - do not proceed to content analysis
- Include build errors in the final report

### Skill Invocation Errors
- Report the error in the corresponding report section
- Continue with remaining stages
- Note the failure in the Summary section

### Missing Dependencies
- Report what's missing (for example, "Style guide not found at references/doc-style-guide.md")
- Mark that stage as "Incomplete" in the report
- Continue with other stages

### Incomplete Stages
If any stage could not be completed, add an "Incomplete Stages" section to the report listing:
- Which stage failed
- Why it failed
- What's needed to complete it

---

## Constraints

- Provide criticism and suggestions rather than direct bulk rewrites.
- Do not modify source code to fix documentation without explicit request.
- Before restructuring large documentation sections (for example, moving files between tutorial and how-to), ask first.
- Before suggesting new coverage entities, categories, or metadata patterns, ask first.
- If code examples seem correct but do not match your understanding of the codebase, ask first.