Draft

Ask review

Write the documentation content following the approved outline

Hats
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:

  • Skimming documentation without actually testing the examples
  • Assuming API signatures are correct because they look plausible
  • Only checking happy-path procedures while ignoring error cases
  • Not flagging version-specific behavior that may break on upgrade
  • Approving documentation that describes intended behavior rather than actual behavior
2

Writer

Focus: Write clear, accurate documentation following the approved outline. Lead 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:

  • Writing documentation from memory instead of verifying against the actual system
  • Using jargon without defining it or linking to a glossary
  • Including code examples that are untested or syntactically invalid
  • Writing procedures without prerequisites or expected outcomes
  • Leaving placeholder sections ("TODO: add example here")
  • Explaining what the system does without explaining why the user would care

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

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