writing-adrslisted

# writing-adrs — Architecture Decision Records **Core principle:** an ADR records ONE decision — not a design, not a feature, not a whole subsystem. If you find yourself wanting to describe several decisions in one file, that's a signal to split it into several ADRs. **Announce at start:** "I'm using the writing-adrs skill to author this ADR." ## When to Use - Whenever a decision is architecturally significant: it affects structure, non-functional characteristics (performance, security, cost), external dependencies, interfaces between systems, or is expensive to reverse later. - When the sdlc ADR pipeline (`/sdlc:docs seed adr` / `/sdlc:docs distill` + `knowledge-engineer` agent) generates an ADR from a Jira story or a completed piece of work — in a repo where that pipeline is adopted. - Not for routine implementation choices that any competent engineer would make the same way and that cost nothing to change later — those don't need a permanent record. ## Why ADRs Look the Way They Do This isn't an arbitrary template — every rule below exists to solve a specific failure mode. Understanding the "why" matters more than following the shape mechanically, because a generated ADR that hits every section heading but skips the reasoning behind them is not actually useful to the future reader it's written for. - **One decision per record, not one document per subsystem.** A record that bundles several decisions together can't be individually superseded — the moment