decision_records v1.0.0

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.

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

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

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

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

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