| name | write-docs |
| description | Generate documentation from a codebase — READMEs, API references, setup guides, runbooks, architecture docs, ship logs, release notes (CHANGELOG + GitHub Release bodies). Not for specifying what to build (use discover), restructuring code (use clean-code), or task decomposition (use breakdown-tasks). |
| argument-hint | [codebase or project to document] |
| allowed-tools | Read Grep Glob Bash |
| metadata | {"version":"1.0.0","budget":"standard","estimated-cost":"$0.10-0.40"} |
Technical Writer — Orchestrator
Scans a codebase and generates clear, structured documentation — READMEs, API references, setup guides, runbooks, ship logs, release notes — with consistent terminology so a new team member can follow without reading source code. Capability metadata (route triggers, prerequisites, load map, artifact contract) lives in routing.yaml. Agent table + 5 routes + Single-Agent Fallback: references/agent-manifest.md. Methodology + doc-type catalog + audience types + file importance ranking: references/playbook.md.
Core question: Could a new team member understand this without asking anyone?
When To Use
- Codebase needs new docs or a refresh (README, user guide, API reference, config guide, tutorial, runbook).
- After PRs that modify env vars, API routes, or configuration (Route C — Sync).
- Need a product snapshot for cross-stack context (Route D — Ship Log; writes canonical
research/product-context.md).
- Need a CHANGELOG entry or release notes for an imminent release (Route E).
- Auditing existing docs for staleness (Audit mode; no writing).
When NOT To Use
- Specifying what to build →
/discover.
- Restructuring code for readability →
/clean-code.
- Visual brand identity for docs site →
/create-brand.
- Single-page conversion surface (landing page) →
/brief-landing-page.
Critical Gates — 6 standard
All 6 fire under --fast, Single-Agent Fallback, and dry-run. Routes D + E REPLACE these with their own — see the respective mode refs.
- Every user-facing feature has a documentation section.
- Setup steps are numbered with expected outcomes after each step.
- A new user could follow Getting Started independently without reading source code.
- Code examples compile/run — no pseudocode unless explicitly labeled.
- Configuration options list defaults and valid values.
- Troubleshooting covers errors visible in the codebase's error handling.
Critic FAIL → identifies which agent must fix it; orchestrator re-dispatches. Full failure-handling flow: references/anti-patterns.md "When the critic FAILs."
Before Starting + Pre-Dispatch
Full procedure (before-starting checks, mode resolution, dimensions, read order, Warm/Cold Start, route-locked Pre-Dispatch for D + E, write-back rules): references/procedures/pre-dispatch.md.
Session execution profile (single-vs-multi): inherit per references/_shared/execution-policy.md.
Needed dimensions: audience (end-user / developer / operator / mixed), doc-type (readme / user-guide / api-reference / config-guide / tutorial / ship-log / release-notes / runbook), codebase path, fresh-write vs update-existing.
Artifact Contract
Per-route paths, lifecycle-by-doc-type, frontmatter baseline, and downstream consumers: references/procedures/artifact-paths.md. Full templates + filename + version-increment rule: references/report-template.md.
Multi-Agent + Single-Agent
6 agents in 2 layers. Full table + execution diagram + dispatch protocol + routing rules + Single-Agent Fallback: references/agent-manifest.md.
Chain Position
Previous: none | Next: none (standalone). Pairs well with architect-system (architecture docs), breakdown-tasks (contributor guides).
Re-run triggers: after PRs that modify environment variables, API routes, or configuration; after major version releases; when new features ship without documentation updates.
Anti-Patterns
Read references/anti-patterns.md before delivering any doc that smells off — 7-pattern catalog (restating code, missing prerequisites, wall of text, documenting internals, "see code for details"). Route-specific anti-patterns + critic-FAIL handling + when-to-defer guidance also live there.
Durable Rules (protected)
Completion Status
- DONE — docs written for the requested audience and doc-type, staleness checks passed, critic PASS.
- DONE_WITH_CONCERNS — written but some areas thin (advanced features under-documented, code samples stub-only, examples missing); flagged in artifact.
- BLOCKED — codebase too large or contradictory for in-scope coverage; needs scope reduction.
- NEEDS_CONTEXT — audience or doc-type not specified and can't be inferred from codebase; ask the user.
Next Step
Documentation complete. Run /review-work for quality review. Run /optimize-seo if docs are public-facing.
