adr

# Writing an ADR

An ADR records **why** a decision was made, for the person who inherits it.
Code shows what was chosen; only an ADR shows what was rejected and what it
cost.

## When to write one

Write an ADR when a decision is **hard to reverse**: it shapes other work,
spans teams, or would be expensive to undo later. Database, framework,
auth model, public API shape, hosting.

Do **not** write one for reversible choices. A helper's name or a file's
location does not need a record.

## Format

Numbered sequentially, never reused: `docs/adr/0001-short-slug.md`.

```markdown
# ADR-0001: <Decision title>

**Status:** Proposed | Accepted — YYYY-MM-DD | Superseded by ADR-####

## Context
The forces at play, and why this needs deciding now. Factual, five minutes
to read.

## Options Considered
### A. <name>
- Description / Pros / Cons
### B. <name> (chosen)
- Description / Pros / Cons

## Decision
What changes. One decision per ADR.

## Consequences
What was traded away. Costs, risks, follow-ups.
```

## Rules

- **One decision per ADR.** Two decisions means two records.
- **Accepted ADRs are immutable.** Changed your mind? Write a new ADR that
  supersedes it. Never edit history to look correct in hindsight.
- **Record the options you rejected**, with why. Six months on, someone will
  ask "why not X?" — the ADR should already answer it.
- **State the cost.** An ADR listing only benefits is marketing. Name what
  the decision gives up.
- **Write it when deciding**, not after implementing. Reconstructed
  reasoning is reasoning you invented.

## Common mistakes

| Mistake | Why it hurts |
|---|---|
| Only recording the chosen option | Loses the comparison that justified it |
| Editing an Accepted ADR | Destroys the record of what was actually believed |
| Writing one per code change | Dilutes the signal until nobody reads any |
| Omitting consequences | Reads as advocacy, not a decision |
| "We chose X because it's better" | Better at what, than what, at what cost? |

## If no options were evaluated

Sometimes a choice is made by fiat — a client mandates it, or someone
already decided. Record that honestly: say no alternatives were weighed and
that the ADR establishes viability, not superiority. A fabricated comparison
is worse than an admitted absence.