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:
- Rewriting the author's voice instead of clarifying their intent
- Prioritizing grammatical perfection over technical accuracy
- Ignoring inconsistent terminology because each instance is individually clear
- Making style changes that alter technical meaning
- Not checking 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:
- Rubber-stamping documentation because the surface-level facts are correct
- Not flagging misleading simplifications that will confuse advanced users
- Ignoring missing edge cases or failure modes
- Assuming the reader has the same context as the author
- Validating against design intent rather than actual behavior
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
Review report exists with findings categorized by type (accuracy, clarity, completeness, consistency). Each finding includes severity, the specific problem, and a concrete fix. The subject-matter-expert has validated technical correctness. Report includes a verdict: approve, revise, or reject.