---
name: documentation-writing
description: >-
  Creates clear, accurate, maintainable technical documentation for any audience.
  Use when READMEs, API docs, architecture docs, user guides, or runbooks are needed,
  or user asks to "document this" or "write docs for".
  NOT for code comments, inline docstrings, or marketing copy.
allowed-tools:
  - Read
  - Glob
  - Grep
  - Bash
---

## Identity & Scope

**Executor:** either
**Model tier:** haiku
**Scope:** Documentation files (markdown, RST, text), source code (read-only for reference)
**Off-limits:** Modifying source code, changing configuration, publishing externally
**Hard rules:** No credentials in output. No deleting files. No spending money. Report via structured output.

## Essential Principles

1. **Audience first** — Identify the reader (developer, user, operator) and write for their context. Guards against: docs nobody can use because they assume wrong knowledge.
2. **Show, don't tell** — Use runnable code examples over prose descriptions. Guards against: docs that explain without demonstrating.
3. **Every example must work** — Verify every code block is copy-pasteable and functional. Guards against: stale examples that destroy reader trust.
4. **Structure by task, not feature** — Organize around "How to X" not "Module X". Guards against: docs that describe internals without helping anyone.

## When to Use
- Creating a README for a new or existing project
- Writing API reference documentation from source code
- Producing setup guides, runbooks, or operational docs
- User asks to "document this" or "write docs for X"
- Updating stale documentation after code changes

## When NOT to Use
- Inline code comments or docstrings — do during implementation
- Marketing copy or landing pages — use communications skill
- Commit messages — use git-commit-messages skill
- Blog posts or articles — use content-writing skill

## Rationalizations to Reject

| Shortcut | Why it's wrong |
|----------|----------------|
| "Write docs from memory without reading code" | Docs that don't match code are worse than no docs |
| "Happy path example is enough" | Users hit errors; document troubleshooting or they're stuck |
| "Prerequisites are obvious" | Nothing is obvious to a new reader — list every dependency |
| "Add examples later" | Docs without examples don't get used |

## Workflow

### Phase 1: Research
**Entry:** Target codebase or feature accessible
**Actions:**
1. Identify the target audience
2. Read source code to understand current behavior and public API
3. Check existing docs — note what's missing, outdated, or wrong
4. List the key tasks a reader needs to accomplish
**Exit:** Audience identified, task list created, current doc state assessed

### Phase 2: Structure
**Entry:** Phase 1 complete
**Actions:**
1. Choose doc type (README, guide, reference, runbook)
2. Create task-based outline: quick start first, reference last
3. Mark which sections need code examples
**Exit:** Outline with headings and example placeholders

### Phase 3: Write
**Entry:** Outline complete
**Actions:**
1. Write the 30-second summary: what, why, how to start
2. Write each section with concrete, runnable examples
3. Include the unhappy path: errors and troubleshooting
4. State all prerequisites explicitly
**Exit:** Complete draft with all sections filled

### Phase 4: Verify
**Entry:** Draft complete
**Actions:**
1. Verify every code example is syntactically correct and matches current API
2. Confirm all prerequisites listed
3. Confirm task-based structure (not feature-based)
4. Confirm output matches required JSON format
**Exit:** All checks pass — report results

## Output Format

```json
{
  "skill": "documentation-writing",
  "status": "completed",
  "worker": "worker-id",
  "summary": "Created README.md: quick start, installation, usage (4 examples), config, troubleshooting",
  "findings": [
    {"item": "README.md — 120 lines, 4 runnable examples", "severity": "info", "detail": "Covers: quick start, pip + source install, CLI and Python API usage, config reference, 3 common error fixes"},
    {"item": "Stale reference in docs/api.md", "severity": "medium", "detail": "docs/api.md references get_user() but code uses fetch_user(). Updated."}
  ],
  "errors": [],
  "elapsed_seconds": 45.2
}
```

**Bad example:** `{"summary": "Wrote some docs", "findings": [{"item": "documentation added"}]}` — no specifics, no file paths, no example count, unverifiable.

## Escalation Triggers

STOP and report to boss when:
- Source code too complex to document accurately without domain expertise
- Existing docs contradict code and you cannot determine which is correct
- Documentation requires describing an unfinished feature
- Need to document external services you cannot verify
- Failed same step 3 times

## Success Criteria

- [ ] Target audience identified and content matches their level
- [ ] Every code example is correct and matches current codebase
- [ ] Prerequisites explicitly listed (OS, versions, dependencies)
- [ ] Task-based structure, not feature-based
- [ ] Quick start gets reader to first result in under 60 seconds
- [ ] Output matches JSON format above
- [ ] No unresolved escalation triggers
