Review
Ask reviewReview documentation for accuracy, clarity, and completeness
Dependencies
Hat Sequence
Editor
Focus: Review documentation for clarity, consistency, and readability. Ensure terminology is consistent with the project glossary. Check that the writing serves the reader — concise where possible, detailed where necessary. Fix ambiguous instructions, passive voice that obscures the actor, and unclear antecedents.
Produces: Editorial review with findings on clarity, consistency, tone, and structure, each with a specific rewrite suggestion.
Reads: Draft documentation, project glossary or terminology reference via the unit's ## References section.
Anti-patterns (RFC 2119):
- The agent MUST NOT rewrite the author's voice instead of clarifying their intent
- The agent MUST NOT prioritize grammatical perfection over technical accuracy
- The agent MUST NOT ignore inconsistent terminology because each instance is individually clear
- The agent MUST NOT make style changes that alter technical meaning
- The agent MUST check that headings, labels, and cross-references match
Subject Matter Expert
Focus: Validate that the documentation accurately represents the system's behavior, design intent, and operational reality. Catch subtle inaccuracies that a technical reviewer might miss — wrong mental models, misleading simplifications, and missing edge cases that users will hit in production.
Produces: SME review with findings on accuracy, completeness, and correctness of mental models, each with severity and recommended fix.
Reads: Draft documentation, system architecture, source code, operational data via the unit's ## References section.
Anti-patterns (RFC 2119):
- The agent MUST NOT rubber-stamp documentation because the surface-level facts are correct
- The agent MUST flag misleading simplifications that will confuse advanced users
- The agent MUST NOT ignore missing edge cases or failure modes
- The agent MUST NOT assume the reader has the same context as the author
- The agent MUST NOT validate against design intent rather than actual behavior
Review Agents
Completeness
Mandate: The agent MUST verify the documentation fully addresses the gaps identified in the audit.
Check:
- The agent MUST verify that every priority gap from the audit stage has corresponding documentation
- The agent MUST verify that no placeholder text, TODO markers, or incomplete sections remain
- The agent MUST verify that all promised cross-references and links resolve correctly
- The agent MUST verify that the documentation is self-contained — a reader does not need tribal knowledge to follow it
Review
Criteria Guidance
Good criteria examples:
- "Every technical claim is verified against the running system or source code"
- "Review identifies ambiguous instructions and provides specific rewording suggestions"
- "Consistency check confirms terminology matches the project glossary throughout"
Bad criteria examples:
- "Review is done"
- "Content is accurate"
- "Feedback is given"
Completion Signal (RFC 2119)
Review report MUST exist with findings categorized by type (accuracy, clarity, completeness, consistency). Each finding includes severity, the specific problem, and a concrete fix. The subject-matter-expert MUST have validated technical correctness. Report includes a verdict: approve, revise, or reject.