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. ## Required Sections Every ADR — hand-authored or pipeline-generated — MUST contain these sections, in this order. One decision per record, not one document per subsystem — a bundled record can't be individually superseded; the moment one part of it changes, a reader can no longer trust any of it. 1. **Title** — a short noun phrase naming the decision, not the problem (e.g. "Use PostgreSQL as the primary datastore", not "Datastore options"). The ADR number belongs in the filename, not necessarily repeated