writing-docs

Use when writing or revising project documentation of any kind — a README, docs-site landing page, tutorial, quickstart, how-to guide, reference page, API doc, cheat sheet, examples catalog, limitations or FAQ page, or changelog — and when consolidating, auditing, or rebuilding a whole docs set. Applies the Diataxis framework (one mode per page), a technical-builder voice, runnable code-sample rules, the conversion skeleton for READMEs and landing pages (a pain-naming opener, one live get-started path with a real-run demo, use cases that show observed behavior, an agent block), standalone-README design, consolidation by rewriting (parallel per-page audits with defects and gems, an explicit merge map with per-page verdicts, alias frontmatter, a link retarget sweep), honesty gates that test docs claims against the real package (reflection gate, extract-and-run, regenerated CLI output, parity-gated demos), findability rules (task-phrased headings, a narrative home for every task), delegated-prose work orders (verbatim landing, surgical fixes tied to audit items, a check-back contract), ship discipline (docs CI on the push as the gate), and a required, triaged slop-cop prose-lint pass. Triggers on "write/rewrite/improve the docs", "write a README", "consolidate/merge the docs", "audit the docs", "write a tutorial", "document this", "getting-started page", "write a cheat sheet", "build an examples catalog", or any natural-language documentation task.