09-core-write-canonical-system-documentation-manual-stylelisted

Trigger whenever you write, restructure, or review LASTING documentation for a system, service, app, server, or pipeline — a README that outgrew itself, a docs/ folder, an in-app docs page, an onboarding guide, or any 'document how X works' task. Also fires when you notice existing docs are diary/incident-log style (dated 'what we did on DATE' files, FIX-NOTES, E2E-TEST-DATE.md, OUTAGE-DIAGNOSIS) and need them turned into a real operator's manual. This is the canonical manual-style standard: a doc answers 'how does this work and how do I run it' for someone who has never seen it, NOT 'what happened to it over time'. Dated incidents are demoted to an incidents/ appendix, never the main doc. Use it so docs stay a manual a new teammate can act on, not an undated pile of war stories.
markkennethbadilla/public-agent-provisioning · ★ 0 · AI & Automation · score 72

Install: claude install-skill markkennethbadilla/public-agent-provisioning

# Write Canonical System Documentation — Manual Style A doc exists to make a stranger productive on a system fast. It answers **how it works and how I operate it**, not **what happened to it**. The default failure is diary rot: dated "fix notes", incident write-ups, and test logs accumulate at the top level until the folder is an archaeology dig, not a manual. This skill is the fixed standard that prevents that. ## The one law: manual, not diary - **Manual** = present-tense, structural, evergreen: Overview → Architecture → How it works → Operations/Runbook → Config & Env → Troubleshooting. Reads true regardless of *when* you read it. - **Diary** = dated, event-shaped, append-only: `E2E-TEST-2026-06-24.md`, `WEBHOOK-OUTAGE-DIAGNOSIS.md`, "what I changed today". Real info, wrong home. - Diary content is not deleted — it is **demoted** to `incidents/` (or `changelog/`) as an appendix. The main doc absorbs the *lasting lesson* (the gotcha, the fix that's now permanent) into Troubleshooting/Architecture; the dated narrative stays in the appendix for provenance. ## Required structure (per system) Every system gets a folder with a `README.md` (the landing/overview) plus these sections — short files, one job each (rule 5a). See `reference/manual-template.md` for the copy-paste skeleton. 1. **Overview** — what it is, who uses it, where it runs (1 screen max). The reader decides in 30s if they're in the right doc. 2. **Architecture** — the moving parts and how they connect; a diagra