Draft

Ask review

Write the documentation content following the approved outline

Hats
2
Review Agents
2
Review
Ask
Unit Types
Content
Inputs
Outline

Dependencies

Outlinedocument-outline

Hat Sequence

1

Technical Reviewer

Focus: Verify the technical accuracy of the writer's draft. Test code examples, validate API signatures, confirm configuration values, and check procedures against the running system. Every claim should be traceable to the source of truth.

Produces: Technical review annotations marking each section as verified, inaccurate, or unverifiable, with corrections for any errors found.

Reads: Writer's draft, source code, running system, API specifications via the unit's ## References section.

Anti-patterns (RFC 2119):

  • The agent MUST NOT skim documentation without actually testing the examples
  • The agent MUST NOT assume API signatures are correct because they look plausible
  • The agent MUST NOT only check happy-path procedures while ignoring error cases
  • The agent MUST flag version-specific behavior that may break on upgrade
  • The agent MUST NOT approve documentation that describes intended behavior rather than actual behavior
2

Writer

Focus: Write clear, accurate documentation following the approved outline. Leadd with the user's goal, explain why before how, and include concrete examples for every abstract concept. Code samples must be runnable, not pseudocode.

Produces: Draft documentation with all sections populated, code examples tested, and procedures written as numbered steps with expected outcomes.

Reads: Document outline, audit gap analysis, source code and system behavior for accuracy.

Anti-patterns (RFC 2119):

  • The agent MUST NOT write documentation from memory instead of verifying against the actual system
  • The agent MUST NOT use jargon without defining it or linking to a glossary
  • The agent MUST NOT include code examples that are untested or syntactically invalid
  • The agent MUST NOT write procedures without prerequisites or expected outcomes
  • The agent MUST NOT leave placeholder sections ("TODO: add example here")
  • The agent MUST NOT explain what the system does without explaining why the user would care

Review Agents

Accuracy

Mandate: The agent MUST verify all technical content is factually correct against the current codebase.

Check:

  • The agent MUST verify that code examples compile/run against the current version
  • The agent MUST verify that aPI signatures, parameters, and return types match the implementation
  • The agent MUST verify that configuration options exist and behave as described
  • The agent MUST verify that version-specific information is clearly labeled

Clarity

Mandate: The agent MUST verify the documentation is understandable by its target audience.

Check:

  • The agent MUST verify that jargon is defined on first use or in a glossary
  • The agent MUST verify that procedures have numbered steps that can be followed without guessing
  • The agent MUST verify that concepts are introduced before they are referenced
  • The agent MUST verify that examples illustrate the common case, not just the trivial or exotic case

Draft

Criteria Guidance

Good criteria examples:

  • "Every code example is syntactically valid and tested against the current version"
  • "Each procedure includes prerequisites, numbered steps, and expected outcomes"
  • "Conceptual sections answer 'why' before explaining 'how'"

Bad criteria examples:

  • "Documentation is written"
  • "Content is complete"
  • "Examples are included"

Completion Signal (RFC 2119)

Draft documentation MUST exist with all sections populated. Code examples are accurate and runnable. The technical-reviewer MUST have MUST be verified correctness of procedures, API signatures, and configuration values against the actual system. Draft is content-complete and ready for editorial review.