docs

Write an Architecture Decision Record for a technical choice, with context, the options considered and their trade-offs, the decision and its consequences, in a fixed format with a status lifecycle (proposed, accepted, superseded), numbered and stored in the repository. Use when asked to "write an ADR", when a team is choosing between technologies, patterns or designs, when someone asks why something was done this way, or to record a decision already made. Not for product requirements or meeting minutes.

Generate an API reference from source with a bundled script that extracts Python docstrings (Google, NumPy and reST styles) and JavaScript/TypeScript JSDoc into Markdown or JSON, lists undocumented public symbols and measures documentation coverage; then fill the gaps and wire the extraction into the docs build. Use when asked to "document this module" or package, when the reference is stale, or to enforce docstrings on public code. Not for OpenAPI documents (use api-contract-review) and not a replacement for Sphinx, mkdocstrings or TypeDoc where already used.

Maintain CHANGELOG.md in the Keep a Changelog format with a bundled script that validates the structure, adds entries under Unreleased in the right category, cuts a release (version, date, compare links) and prints a version's section. Use when asked to "update the changelog", when a change needs a changelog line, when preparing a release, or when the changelog has drifted from the format. Not for generating entries from git history (use release-notes for that, then add the entries here).

Write a developer onboarding document that gets a new team member from a clean machine to a merged change: environment setup verified step by step, how the code is organised, how to run and test it, the configuration it needs, the deployment path, who owns what, and the first tasks. Use when asked to "write an onboarding guide", when a project has none, when the last new joiner struggled, or before a team grows. Not for user-facing documentation (use readme-author) and not for HR onboarding.

Write a blameless incident postmortem from the timeline, logs, chat transcript and metrics: impact with numbers, a minute-by-minute timeline, contributing causes found with a structured analysis rather than a single root cause, what went well and what did not, and action items with owners, deadlines and a check that they would have prevented or shortened the incident. Use when asked to "write up what went wrong" after an outage, a data incident, a security event or a serious near-miss. Not for bug reports (use bug-repro-minimiser) and not for performance reviews of people.

Write or rewrite a README that answers what the project is, who it is for, how to install and use it in under five minutes, and where everything else lives, using a fixed section order and a quality checklist (first screen, copy-pasteable commands verified to work, no stale claims). Use when asked to "write a README", when a repository has none or it is out of date, or when a project is about to be published. Not for API reference generation (use api-docs-from-code) and not for marketing copy.