Draft
Ask reviewWrite the documentation content following the approved outline
Dependencies
Hat Sequence
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
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.