Review

Ask review

Review documentation for accuracy, clarity, and completeness

Hats
2
Review Agents
1
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 (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
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 (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.