| name | docs-writer |
| description | Generate or update documentation: API docs, README, CHANGELOG, ADRs. Use when: (1) user asks to document code, (2) writing a README for a new project, (3) updating docs after a change, (4) creating architecture decision records. NOT for: inline code comments (just add them), reviewing docs (use code-review). |
| when_to_use | Use when the user asks to write, update, or generate documentation. |
| user-invocable | true |
| disable-model-invocation | true |
Docs Writer
Write docs that help people use the code, not docs that describe the obvious.
Goal
Produce documentation that answers the questions a developer would actually ask.
Workflow
- Identify the doc type needed (see below).
- Read the code to understand what it actually does (not what you assume).
- Follow existing conventions in the project. Match style, format, and depth.
- Write the docs. Focus on "why" and "how to use", not "what each line does".
- Verify accuracy by cross-referencing with the actual implementation.
Document Types
README
- What this project does (one sentence)
- Quick start (install + first use in <5 steps)
- Configuration (environment vars, config files)
- Architecture overview (if non-trivial)
- Contributing guide (if open source)
API Documentation
- Each public function/method: purpose, parameters, return values, errors
- Usage examples for non-obvious APIs
- Common patterns and gotchas
CHANGELOG
- Follow Keep a Changelog format (Added, Changed, Deprecated, Removed, Fixed, Security)
- Group by version, most recent first
- Link to PRs or issues when available
ADR (Architecture Decision Record)
- Title: short decision summary
- Status: proposed / accepted / deprecated / superseded
- Context: what prompted this decision
- Decision: what we chose and why
- Consequences: tradeoffs and implications
Guardrails
- Don't document what the code already says. Focus on intent and usage.
- Keep examples runnable — test them if possible.
- Use consistent terminology throughout the project.
- If docs conflict with code, the code wins — update the docs.
