# Architecture Decision Records

Each ADR records *that* a decision was made and *why* — not how it's implemented. Files use sequential numbering: `0001-slug.md`, `0002-slug.md`, …; scan for the highest number and increment.

An ADR is worth writing only when **all three** are true:

1. **Hard to reverse** — changing your mind later is costly.
2. **Surprising without context** — a future reader would 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.

Most ADRs are a single paragraph. Add optional `Status` frontmatter, `Considered Options`, or `Consequences` sections only when they add real value. These first four were seeded from the conventions already baked into `CLAUDE.md`, `MERGE_PLAN.md`, and the code; `/grill-with-docs-codex` adds new ones inline as decisions crystallise.