documentation

---
name: documentation
description: Use when bootstrapping docs or when a task may change public behavior, APIs, CLI commands, configuration, environment variables, schemas, setup, deployment, operations, architecture, release notes, durable project decisions, README, reference docs, changelog, ADRs, playbooks, or agent guidance.
license: MIT
---

# Documentation Skill

## Goal

Keep documentation synchronized with the project state. Treat stale documentation as a project bug, but do not create documentation churn for internal-only changes that do not affect users, operators, contributors, architecture, or future agents.

## Default Workflow

1. Inspect relevant existing documentation before editing docs, and before code changes when docs may influence the implementation.
2. Identify whether the task changes interface, structure, or project knowledge.
3. Make the code or project change.
4. Verify the actual change by reading the modified files or running `git diff`. Do not rely on memory of what was just done.
5. Update only the affected documentation, grounded in what step 4 revealed.
6. Check for contradictions between code, README, docs, changelog, and agent guidance.
7. Summarize documentation work in the final response.

## Decide Whether To Update Docs

Always check for documentation impact. Update docs only when at least one answer is "yes":

- **Interface:** Did public behavior, APIs, routes, CLI commands, config, env vars, schemas, file formats, installation, or usage change?
- **Structure:** Did architecture, module responsibilities, dependency boundaries, deployment, operations, or contributor workflow change?
- **Knowledge:** Was an important decision made, a long-lived tradeoff accepted, a limitation discovered, or technical debt made visible?

Usually do not update docs for purely internal refactors, tests, formatting, small implementation fixes with no visible behavior change, or mechanical cleanup unless existing docs would become misleading.

## Evidence Before Editing

Base documentation strictly on verifiable project evidence. Do not summarize or paraphrase what the agent believes it just did — read the actual current state of files or diff output:

- `git diff` or the modified files themselves — the authoritative record of what changed
- README, existing docs, AGENTS.md, CLAUDE.md, or package-level READMEs
- package scripts, Makefile, task files, CI config, Docker files, deployment manifests
- source exports, route definitions, CLI parsers, config schemas, env validation, database migrations
- tests, fixtures, examples, sample configs, release metadata
- explicit user instructions

Do not invent commands, support status, APIs, performance claims, compatibility promises, or deployment steps. If something cannot be verified, write it as an open question or omit it.

## Production Guardrails

- Keep documentation changes proportional to the project change.
- Prefer surgical edits over broad rewrites, reorganizations, or style-only churn.
- Preserve warnings, limitations, compliance notes, security guidance, and operational runbooks unless verified project changes make them obsolete.
- Do not document secrets, private credentials, internal tokens, or sensitive customer data.
- Do not duplicate generated or authoritative sources of truth; link to OpenAPI specs, schemas, package metadata, or generated reference docs when those are canonical.
- Do not create empty files, placeholder sections, blank tables, or speculative roadmap items.
- Do not rename or move established docs unless the user asked or the existing structure is clearly broken.

## Common Rationalizations

Both stale docs and documentation churn are bugs. Each excuse below leads to one or the other; the reality column is the rule.

| Excuse | Reality |
|---|---|
| "Docs can wait — I'll open a follow-up." | "Later" usually means never. A changed command, env var, required step, or public behavior ships with its docs in the same change. |
| "The code, schema, or error message is self-documenting." | Operators and contributors read docs, not your validator. If setup or public behavior changed, document it. |
| "Review or CI will catch the missing doc." | That means rework and a stale main until then. Ship the change complete. |
| "It's small, it's late, or the lead said just ship the code." | Size, timing, and "ship it" do not lower severity. A missing required step stays Critical. |
| "While I'm here, I'll reorganize or rewrite for clarity." | Out-of-scope churn hides the real change and risks regressions. Keep edits surgical; file cleanups separately. |
| "The wording is dated, so I might as well refresh it." | "Not wrong" needs no edit. Only fix docs the current change made misleading. |
| "A CHANGELOG entry or ADR would be more thorough." | Internal-only changes with no user-visible effect and no durable decision earn neither. Thorough means documenting what changed, not everything. |

## Red Flags

Stop and re-check when you catch yourself about to under-document:

- "Docs can wait / follow-up ticket" for a changed command, env var, setup step, or public behavior
- "The code is self-documenting" for an interface or setup change
- Merging a doc-worthy change with docs left stale

Or about to over-document, when nothing user-visible, structural, or durable changed:

- "While I'm here, I'll also reorganize, rewrite, or polish" unrelated docs
- Adding a CHANGELOG entry or ADR for an internal-only change with no durable decision
- Editing wording that is dated but not wrong or misleading

When unsure, make the smallest edit that keeps the docs true to the current change — no less, no more.

## Update Map

Apply every matching row, but keep the edit as small as the change allows.

| Change | Update |
|---|---|
| New public feature | README or usage docs; reference docs if there are commands, APIs, config, or schemas |
| Public API, route, CLI, config, env, or file-format change | Reference docs; README if common usage changes |
| Breaking change or deprecation | README migration note; CHANGELOG if present; reference docs |
| Setup, install, or development workflow change | README; getting-started or development docs; AGENTS.md if present |
| Deployment, operations, or incident response change | Operations docs or playbook; README only if users need the entry point |
| Architecture or dependency-boundary change | Architecture docs; ADR only when the decision is durable and has meaningful tradeoffs |
| Important limitation or follow-up | Roadmap, `docs/known-issues.md`, decisions, or the nearest existing planning document |
| Release preparation | CHANGELOG or release notes; README only if current status or usage changed |
| Documentation structure change (reorganize, rename, split, merge docs) | Update all internal links; update README Documentation section if it lists the moved files; do not move established files unless the user asked or the current location is clearly broken |

For detailed structures and examples, read [references/document-map.md](references/document-map.md).

When creating an architecture, reference, or playbook document, start from the fill-in templates in [references/templates.md](references/templates.md).

## Bootstrap Rules

When documentation is missing or nearly empty, create the smallest useful set based on project size:

- Tiny script: `README.md`; update existing agent guide only if present.
- Small library or CLI: `README.md`, optional `CHANGELOG.md`, and one focused docs file if README would become too large.
- App, service, infrastructure project, or monorepo: `README.md` plus only the docs that can be filled with real information now.

Do not create empty placeholder docs. Prefer a short accurate README over a large template with blanks.

For bootstrap templates, read [references/bootstrap.md](references/bootstrap.md).

## Decision Records

Record an ADR only for decisions that are durable, difficult to reverse, cross module or operational boundaries, introduce important dependencies, or encode a tradeoff future agents must understand.

Do not create ADRs for routine implementation choices, local cleanup, small bug fixes, or choices already obvious from code.

For the ADR template, read [references/adr.md](references/adr.md).

## Existing Project Rules

- Preserve the project's current documentation style and file organization when it is coherent.
- Prefer updating existing docs over introducing new files.
- For large documentation sets, inspect and update only the docs related to the change unless a contradiction requires broader cleanup.
- If a project already has `AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, or package-level agent guidance, update the existing file that owns the rule.
- Create a new `AGENTS.md` only during documentation bootstrap or when the user asks for agent guidance.
- In monorepos, keep workspace-level docs at the root and package-specific usage/API docs inside the package.

## Freshness Check

Before finishing, fix documentation issues in this order of severity:

1. **Critical** — describes removed behavior, commands, files, config keys, routes, or setup steps that no longer exist; omits a newly required step, env var, migration, or operational procedure
2. **High** — contradicts source code, examples, tests, or package metadata
3. **Low** — makes unverifiable claims; contains TODOs that are now wrong or obsolete

## Final Response

End with a short documentation summary:

```txt
Documentation updated:
- README.md: updated usage for the new import command
- docs/reference.md: added API parameters
```

If no documentation changed, say:

```txt
Documentation checked; no updates were needed because behavior, APIs, setup, and architecture did not change.
```