# 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.

## 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.