# ADR — Architectural Decision Record

ADRs live in `docs/adr/` with sequential numbering: `0001-slug.md`,
`0002-slug.md`, etc. Create `docs/adr/` lazily — only when the first ADR is
needed. To number a new one, scan `docs/adr/` for the highest number and add one.

## When to offer an ADR

Offer one only when **all three** are true:

1. **Hard to reverse** — the cost of changing your mind later is meaningful.
2. **Surprising without context** — a future reader will look at the code and
   wonder "why on earth did they do it this way?"
3. **The result of a real trade-off** — there were genuine alternatives and one
   was picked for specific reasons.

If any of the three is missing, skip it. Easy to reverse → you'll just reverse
it. Not surprising → nobody will wonder. No real alternative → nothing to record
beyond "we did the obvious thing". Do not create an ADR for every small choice.

**Scope test (ADR vs spec).** Both an ADR and a spec are durable records, so the
split isn't lifetime — it's scope. A spec captures the shape of *one piece of
work* (what we're building and why); an ADR captures a single decision that is
*cross-cutting* — it matters beyond that one piece of work, and a future reader
elsewhere will need its rationale. So record a decision in an ADR only when it
applies beyond the scope of the spec that introduced it. Decisions local to the
current work belong in the spec's "Decisions and rejected alternatives" section,
not here. (The transient, stale-able document is the detailed implementation
plan — a separate artifact, not produced by this skill.)

## Template

```markdown
# {Short title of the decision}

{1-3 sentences: what's the context, what we decided, and why.}
```

That's it. An ADR can be a single paragraph. The value is recording *that* a
decision was made and *why* — not in filling out sections.

## Optional sections

Add these only when they earn their place (most ADRs won't need them):

- **Status** frontmatter (`proposed | accepted | deprecated | superseded by
  ADR-NNNN`) — useful when decisions get revisited.
- **Considered options** — only when the rejected alternatives are worth
  remembering (otherwise someone re-proposes them in six months).
- **Consequences** — only when non-obvious downstream effects need calling out.