---
name: "decision_records"
description: "Write architecture decision records (ADRs): when a decision deserves one, the format (Nygard vs MADR), the immutable lifecycle, and a CLI to create numbered records and regenerate the index. Use when an agent or human says 'record this decision', chooses between significant alternatives, or asks why the codebase is shaped the way it is."
---

# Decision Records (ADRs)

## Purpose

Capture *why* a non-trivial technical or architectural choice was made — the
context, the options, the decision, the consequences — as a short, dated,
numbered markdown file that lives next to the code. ADRs stop teams from
re-litigating old decisions and give future contributors the reasoning behind
the codebase's shape.

## Workflow

1. **Decide whether an ADR is warranted.** Write one when the decision is
   significant and hard to reconstruct later:
   - adopting or replacing a framework, library, database, or deployment pattern
   - data-storage or integration patterns that affect multiple areas
   - cross-cutting conventions (error handling, logging, auth, i18n)
   - hard-to-reverse choices, or choices driven by non-functional requirements
     (performance, compliance, cost, security)
   - anything a future contributor would ask "why did they do it this way?"
   - anything you suspect will be questioned later

   Skip ADRs for routine choices (which JSON parser), minor version bumps,
   tactical bug fixes, or anything the code makes self-explanatory.

2. **Gather the decision facts before writing.** Confirm with the person driving
   the decision: what was chosen, what else was considered and why it lost, and
   what the trade-offs are. Never invent options or rationale they did not
   provide or confirm.

3. **Pick a format.** Use the lean Nygard format (Title, Status, Context,
   Decision, Consequences) when the decision is clear and speed matters. Use
   MADR when the choice was between several concrete options and the pros/cons
   and drivers matter — its required sections are *Context and problem
   statement*, *Considered options*, *Decision outcome* (chosen option +
   justification), and *Consequences*. Templates for both live in
   `references/templates.md`.

4. **Create the record with the CLI** (`bin/adr.py`) so numbering and the index
   stay consistent:
   - `adr new --dir docs/adr --title "Use PostgreSQL for registry storage"` —
     creates the next numbered file `NNNN-kebab-case-title.md` from the template.
   - `adr index --dir docs/adr` — regenerates `README.md` as a table of all ADRs.
   - `adr show --dir docs/adr --query postgres` — lists records matching a title/status query.

5. **Fill in the content.** Title states the decision ("Use PostgreSQL for
   registry storage", not "Database"). Context describes the problem and forces
   only — no solution in Context. Decision is active voice ("We will…").
   Consequences list positives, negatives, and risks; an ADR with no downsides
   was justified, not analyzed. Record the rejected options *and why they lost* —
   that is the part future teams cannot reconstruct. Keep it to one page.

6. **Handle lifecycle changes by superseding, never rewriting.** An accepted ADR
   is immutable. When a decision changes: write a new ADR, set the old one's
   status to `Superseded by ADR-NNNN` (with a link), and have the new one link
   back. Statuses: `Proposed` (under discussion), `Accepted` (binding, permanent),
   `Deprecated` (no longer relevant, kept for history), `Superseded by ADR-NNNN`.

## Output Contract

Each ADR file written to `<dir>/NNNN-kebab-case-title.md` (zero-padded 4-digit
numbers, starting at 0001) contains: title, status, date (YYYY-MM-DD),
deciders/owner, Context, Decision, Alternatives considered, Consequences.
`README.md` in the same directory is a regenerated table: number, title, status,
date, link. No record is ever edited after acceptance — change arrives only via
a new superseding record.

## Operating Rules

1. Never invent options, drivers, or rationale the decider did not provide or confirm.
2. Never edit an accepted ADR in place to change the decision — supersede it.
3. Keep each record to one page; an ADR is a record of a decision, not a design document.
4. Title states the decision itself, as a short noun phrase.
5. Record honest negative consequences; skip the record rather than fabricate them.
6. Use the CLI for numbering and indexing; hand-numbering causes collisions.
7. Don't ADR routine choices — ceremony without significance trains people to ignore the log.