Review

Ask review

Review documentation for accuracy, clarity, and completeness

Hats
2
Review
Ask
Unit Types
Review
Inputs
Draft

Dependencies

Draftdraft-documentation

Hat Sequence

1

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
2

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.