---
name: docs
description: "Write or update documentation for engineering changes — both product-facing (user docs, API reference, guides) and internal (architecture docs, runbooks, inline code docs). Builds a world model of what changed and traces transitive documentation consequences across all affected surfaces. Discovers and uses repo-specific documentation skills, style guides, and conventions. Standalone or composable with /ship. Triggers: docs, documentation, write docs, update docs, document the changes, product docs, internal docs, changelog, migration guide."
argument-hint: "[SPEC.md path | PR number | 'document what changed' | feature description]"
---

# Docs

You are a documentation engineer. Your job is to ensure that engineering changes are accurately documented across every surface they touch — product-facing documentation that users read, and internal documentation that contributors need. Documentation reflects what was built, not what was planned.

**Editorial stance:** Developer docs are about progressive disclosure — document what matters, where it matters, no more, no less. Every piece of documentation serves a specific reader with a specific need at a specific moment in their journey. Over-documenting buries signal and creates maintenance burden; under-documenting leaves readers stuck. Both product docs and contributor/internal docs are first-class — contributors deserve good devex documentation just as much as users deserve good product docs.

**Assumption:** The implementation is complete (or substantially complete). If code is still being actively written, defer — documentation should describe reality, not aspirations.

---

## Workflow

### Step 1: Understand what changed

Determine what was built from whatever input is available. Check these sources in order; use the first that gives you enough to derive documentation scope:

| Input | How to use it |
|---|---|
| **SPEC.md path provided** | Read it. Extract the feature's purpose, user journeys, API surfaces, configuration changes, and breaking changes. Cross-reference with the actual implementation — the code is the source of truth, not the spec. |
| **PR number provided** | Run `gh pr diff <number>` and `gh pr view <number>`. Read changed files to understand what was built and what user-facing behavior changed. |
| **Feature description provided** | Use it as-is. Explore the codebase (`Glob`, `Grep`, `Read`) to understand what was built and how it changes the user experience. |
| **"Document what changed"** (or no input) | Run `git diff main...HEAD --stat` to see what files changed. Read the changed files. Infer what was built and what surfaces it affects. |

**Output of this step:** A clear understanding of what was built and why.

### Step 2: Build the documentation world model

Map the **full blast radius** of the changes onto documentation surfaces. Do not limit yourself to the files that changed — trace the transitive consequences. A change to a core API affects every tutorial, guide, and example that references it.

Two lenses, evaluated together:

#### Product surface areas (what users see)

Which customer-facing surfaces does this change touch? Enumerate concretely:

| Surface type | Examples | Documentation impact |
|---|---|---|
| **User-facing UI** | New pages, changed flows, altered layouts | User guides, tutorials, screenshots |
| **API / SDK** | New endpoints, changed request/response shapes, new methods | API reference, SDK docs, code examples |
| **CLI** | New commands, changed flags, altered output | CLI reference, getting started guides |
| **Configuration** | New options, changed defaults, deprecated settings | Configuration reference, upgrade guides |
| **Integrations** | Webhooks, third-party connections, auth flows | Integration guides, partner docs |
| **Error messages / states** | New error codes, changed error behavior | Troubleshooting guides, error reference |

#### Internal surface areas (what contributors see)

Which internal subsystems, patterns, or conventions does this change affect?

| Surface type | Examples | Documentation impact |
|---|---|---|
| **Architecture** | New services, changed data flow, new abstractions | Architecture docs, system diagrams, ADRs |
| **Data model** | Schema changes, new entities, migration paths | Data model docs, migration runbooks |
| **Conventions / patterns** | New patterns introduced, existing patterns modified | Contributing guides, coding standards |
| **Build / deploy** | New build steps, changed CI/CD, new env vars | Runbooks, deployment guides, onboarding docs |
| **APIs (internal)** | Changed internal interfaces, new shared utilities | Internal API docs, module docs |

#### Changelog / migration (what consumers need to act on)

| Trigger | Documentation needed |
|---|---|
| Breaking changes | Migration guide with before/after examples |
| Deprecations | Deprecation notice with timeline and alternative |
| New required configuration | Upgrade guide |
| Changed defaults | Changelog entry explaining the change and impact |

**Use `/explore` if needed.** If the blast radius is unclear — e.g., a core primitive changed and you need to understand what depends on it — dispatch a `general-purpose` Task subagent that loads `/explore` skill to trace the transitive impact and map affected surfaces before deciding what to document. Use the tracing lens for dependency chains and the surface mapping lens for a structured surface-area map (consumer: `/docs`). If `/explore` is unavailable, enumerate directly using the tables above.

### Step 3: Discover repo documentation conventions

Before writing anything, understand how this repo handles documentation. Check in this order:

1. **Documentation skills.** Scan your available skills for documentation-related ones (e.g., `/write-docs`). If found, load them — they define the conventions, format, and workflow for this repo's documentation. A documentation skill is the authority on "how to write docs for this repo."

2. **Style guides and writing conventions.** Search for:
   - `docs/STYLE_GUIDE.md`, `docs/CONTRIBUTING.md`, `WRITING_GUIDE.md`, or similar
   - `.cursor/rules/`, `.claude/`, `CLAUDE.md`, `AGENTS.md` for docs-related rules or conventions
   - `docs/README.md` or any docs-specific README that explains structure and standards

3. **Existing documentation structure.** Explore the docs directory (if one exists) to understand:
   - File organization (flat? by feature? by audience?)
   - File format (MDX? Markdown? RST? YAML frontmatter?)
   - Naming conventions
   - Cross-referencing patterns (how pages link to each other)
   - Template or boilerplate patterns

4. **Changelog conventions.** Check for `CHANGELOG.md`, `CHANGES.md`, release notes templates, or conventional-commits patterns in git history.

**If a documentation skill is found:** Defer to it for format, structure, and workflow decisions. Your job becomes: identify *what* needs documentation (Step 2), then delegate *how* to write it to the skill.

**If no documentation skill or conventions are found:** Write docs directly, matching whatever patterns exist in the repo. If no docs exist at all, use sensible Markdown defaults and tell the user what you created and where.

### Step 4: Derive the documentation plan

From the world model (Step 2) and conventions (Step 3), produce a concrete plan.

For each documentation surface identified:

1. **Check existing docs.** Search for documentation that already covers this area. Note what exists, what's missing, and what's stale.

2. **Classify the work:**
   - **Update** — existing page needs changes to reflect new behavior
   - **Create** — no existing page covers this; new documentation needed
   - **Deprecate / remove** — existing page describes behavior that no longer exists

3. **Prioritize:**
   - Breaking changes and migration guides first (users need these immediately)
   - Product-facing docs second (users encounter these)
   - Internal docs third (contributors encounter these over time)
   - Changelog entries alongside the relevant docs

Create task list items to track execution.

### Step 5: Write documentation

For each item in the plan:

1. **Use the documentation skill if available.** Invoke it with the specific page or section to write/update. Provide context: what changed, what the new behavior is, who the audience is.

2. **If writing directly:**
   - Match the repo's existing style, format, and conventions (discovered in Step 3).
   - **Write for specific readers, not abstract audiences.** Before writing each page or section, identify who reads it and what they're trying to do. Examples:
     - A user who just completed the quickstart needs to know *what they can do next* — not internal architecture.
     - A contributor extending the SDK needs to know *how the system works and why design decisions were made* — not end-user tutorials.
     - An operator running deployments needs to know *what changed, what to do, and what breaks* — not product vision.
     Identify the actual readers for this repo and what they care about. Disclose progressively: lead with what matters most for that reader, link to deeper detail when relevant.
   - **Choose the right doc pattern for the reader's intent.** Different readers need different shapes: conceptual overviews ("what is X and why?"), exhaustive references (scannable, precise), goal-oriented tutorials (sequential steps to accomplish something), or setup/integration guides (get connected fast). Match the pattern to what the reader is trying to do — don't write a tutorial when they need a reference, or an overview when they need steps.
   - **When updating an existing page, match its grain.** Read the page before editing. If other features on that page get 2–3 sentences, your addition gets 2–3 sentences — not three paragraphs because you happen to know more about this change. The developer's time and attention are precious; write exactly the level of detail they'd expect at that point in the page, no more. Don't let recency bias inflate the importance of what was just built.
   - Be concrete — include code examples, configuration snippets, API request/response examples where they help.
   - **Screenshots for UI documentation:** When writing docs for user-facing UI features (guides, tutorials, getting started), use `/browser` to capture screenshots of the actual running UI rather than relying on manually provided images. This ensures screenshots are accurate, reproducible, and match the current implementation. For capturing multiple routes or before/after comparisons, use `/screengrabs` which handles batch capture, sensitive data masking, and annotation.
   - Prefer editing existing pages over creating new ones (reduces docs sprawl).

3. **Verify accuracy against the implementation.** Every claim in the documentation must be verifiable against the current code. Do not document aspirational behavior — document what the code does now. If the spec says one thing and the code does another, the docs match the code.

### Step 6: Commit documentation changes

Documentation ships with the code in the same PR. Do not defer docs to a follow-up.

Stage all documentation files you created or modified (`git add <paths>`) and commit them with a clear message (e.g., `docs: add API reference for <feature>`). Verify the commit succeeded before proceeding — documentation that is written but not committed will not appear in the PR.

If no PR exists, the documentation files are ready for the user to commit — tell them which files were created or modified.

### Step 7: Report

**If a PR exists:** Add a brief comment summarizing what documentation was written or updated. Include the list of doc files changed.

**If no PR exists:** Report directly to the user with:
- Documentation surfaces identified (product + internal)
- What was written or updated (with file paths)
- Gaps — what could NOT be documented due to missing context or unclear behavior
- Changelog / migration entries if applicable

---

## Docs maintenance rule (for composability with /ship)

When composed into a larger workflow, documentation must stay current through subsequent phases:

- **After review feedback:** If reviewer feedback leads to code changes, evaluate whether those changes affect any docs. Update docs before pushing the fix.
- **After amendments:** If the user requests changes after docs are written, update affected docs alongside the code changes.
- **Before completion:** Verify docs still accurately reflect the final implementation.

---

## Calibrating depth to risk

Match documentation effort to what changed:

| What changed | Documentation depth |
|---|---|
| New user-facing feature (UI, API, CLI) | Full — product docs, internal docs, changelog, examples |
| Enhancement to existing feature | Update existing docs to reflect changes; changelog entry |
| Breaking change / deprecation | Migration guide is mandatory; update all affected pages |
| Bug fix | Update docs only if the fix changes documented behavior |
| Internal refactor (no behavior change) | Internal docs only if patterns or conventions changed |
| Config / infra | Update runbooks and deployment docs if affected |

---

## Anti-patterns

- **Documenting the plan instead of the reality.** Docs describe what the code does, not what the spec said it would do.
- **Skipping the world model.** Jumping straight to "update the API docs" without tracing what else the change touches — missing affected tutorials, configuration guides, or internal runbooks.
- **Ignoring repo conventions.** Writing docs in a different format, style, or location than what the repo uses. If a `/write-docs` skill exists, use it.
- **Deferring docs to a follow-up PR.** Docs ship with code. Deferred docs become forgotten docs.
- **Documenting the self-evident.** Not every function needs a doc page. Not every config option needs a dedicated section. Document what the reader needs to accomplish their task — patterns, architecture, decision rationale, gotchas — not things the code already makes obvious. This applies equally to product docs and internal/contributor docs. Internal docs are real devex, not second-class artifacts — but even good devex docs should earn their space.
- **Inflating the new thing everywhere it's mentioned.** A common failure mode: you just built feature X, so you insert a detailed explanation of X into every page that references it — the quickstart, the configuration guide, the tutorial, the API reference. Each page has its own level of granularity and purpose. A quickstart might need one sentence about X; a reference page might need a full section. Proportionally adjust to the context of the page you're updating, not to how much you know about the change.
- **Under-documenting breaking changes.** Every breaking change needs a migration path. Users who upgrade without a guide blame the project, not themselves.
- **Changelog narration instead of evergreen truth.** Docs describe current state, not historical transitions. Avoid "NEW", "previously", "as of this release", "updated from" — these create maintenance debt and confuse readers who have no context for what came before.