# NNNN — Short imperative title

**Status:** proposed | accepted | superseded by [NNNN](NNNN-slug.md) · **Date:** YYYY-MM-DD

## Context

The situation that forces a choice. What's true right now, what pressure it creates,
and what breaks if nothing changes. Write enough that someone who wasn't there can
tell whether this still applies — including the constraints that turn out to matter
later (team size, scale, dependencies, deadlines).

No decision here. Just the facts.

## Decision

What was chosen, stated plainly and in the active voice. One or two sentences is
usually right.

## Alternatives considered

What else was on the table and why it lost. This is the part future-you actually
needs — a rejected option with no recorded reason gets re-litigated every six months.

- **Option** — why not.

## Consequences

What follows, good and bad. Be honest about the costs; a record listing only benefits
is marketing, not a decision.

- What this makes easy
- What this makes hard
- New dependencies, obligations, or known holes it opens
- How reversible it is, and what reversing would cost

---

## How to use this directory

- One file per decision, numbered sequentially: `0001-slug.md`. Numbers are never
  reused, and files are never deleted — a decision that stops applying gets its status
  changed to **superseded**, with a link to the one that replaced it. The trail of
  wrong turns is the point.
- Write one when a choice would be expensive to reverse, when it constrains future
  work, or when the reasoning wouldn't be obvious from reading the code. Skip it for
  anything the code makes self-evident.
- Write it **when the decision is made**, not afterwards. Reconstructed rationale is
  mostly fiction.
- Link to the record from wherever the choice shows up — `ROADMAP.md`,
  `architecture.md` — rather than restating the reasoning in both places.