| name | doc-review |
| description | Review documentation for quality, structure, and convention compliance. Use when the user wants to review docs, audit a page or section, check if content is clear, evaluate information architecture, or assess navigation. Do NOT use when the user wants to write or fix docs — use doc-write for that. Triggers on "review the docs", "audit this page", "is this getting-started page clear", "check the implementation guide section". |
Doc Review
Evaluate technical docs against the Diátaxis framework, information-architecture best practices, and the project's CLAUDE.md.
Before reviewing
- Read the project's CLAUDE.md — it defines all site-specific conventions. Use it as your compliance checklist for writing style, components, link format, and frontmatter. If no CLAUDE.md exists, read 3-4 existing pages to infer conventions.
- Read
docs.json to understand navigation structure.
- Determine review scope — single page, section, or full site. If unclear, ask the user which scope they want.
Page-level review
- Diátaxis classification — Identify the doc type (tutorial, how-to, reference, explanation). Does the content match? Common issue: tutorials mixed with reference material, or how-to guides that teach instead of solving.
- Content quality — Clear title? Accurate description? Complete for its doc type? Factually correct and current?
- Structure — Logical flow? Appropriate depth?
- CLAUDE.md compliance — Check the page against every rule and convention in the project's CLAUDE.md (frontmatter, components, links, writing style, don'ts).
- Link validation — Internal links resolve to existing files? (Use Glob/Grep to verify.)
Section-level review
- Read all pages in the section.
- Check navigation order — logical progression?
- Identify gaps — missing pages for common user tasks?
- Check Diátaxis balance — right mix of doc types?
- Verify cross-linking between related pages.
- Assess consistency in voice, structure, and components.
Site-level review
- Is the top-level navigation intuitive?
- Are tutorials, how-to guides, reference, and explanation clearly separated?
- Can new users find getting-started content quickly? Can experienced users find reference quickly?
- Structural issues: orphaned pages, deep nesting (>3 levels), overloaded sections, missing landing pages.
Output format
Categorize findings as:
- Critical — Broken functionality, factual errors, missing required content.
- Improvement — Clarity issues, structural problems, missing best practices.
- Suggestion — Nice-to-have enhancements.
For each: Location (file:line or section), Issue, Recommendation.
End with a summary: findings by category, overall assessment, top 3 priorities.
