Decision record

A decision that lives only in a meeting has a half-life of about three weeks. After that it gets re-litigated by people who were in the room. An ADR is the cheapest insurance against having the same argument twice.

When to use this

Write a record when a decision is hard to reverse, expensive if wrong, or surprising to a newcomer. That last one matters most: if someone joining the team would ask "why on earth is it like this?", it needs a record.

Do not write one for reversible, obvious or purely local choices. An ADR per variable name is how teams learn to ignore ADRs.

Procedure

1. Confirm a decision was actually reached

Discussions often end without concluding. Before writing anything, check that someone committed to a course of action. If the discussion merely converged on a preference, say so and stop — writing it up as settled will mislead everyone later.

With Wisprnote: get_meeting_knowledge returns decisions separately from topics. If the decisions list is empty for a meeting that felt conclusive, that is a real finding worth reporting back.

2. Recover the alternatives

The options that were rejected are the most valuable part of the record and the first thing lost. Without them the record reads as arbitrary, and the same alternative gets proposed again six months later.

For each one: what was it, and what specifically ruled it out?

3. Recover the constraints

Capture what was true at the time — team size, deadline, cost ceiling, a library's limitations, the version of something you were pinned to. Decisions are conditional on constraints, and constraints expire. A record without them cannot be safely revisited.

4. Write it

Keep to the standard shape so it is skimmable:

# ADR-<NNN>: <decision, as a statement not a question>

- **Status:** proposed | accepted | superseded by ADR-<NNN>
- **Date:** <YYYY-MM-DD>
- **Deciders:** <names>
- **Source:** <meeting, PR thread or issue — with a link or id>

## Context

<The situation that forced a choice. What problem, what pressure, what constraints
applied at the time. Written so a newcomer needs no other document.>

## Decision

<What was chosen. Active voice, one or two sentences. "We will …">

## Alternatives considered

### <Option B>
<What it was.> **Rejected because:** <specific reason.>

### <Option C>
<What it was.> **Rejected because:** <specific reason.>

## Consequences

**Accepted costs:** <what becomes harder, what is given up>
**Benefits:** <what becomes easier>
**Revisit if:** <the condition that would make this decision wrong — the most
useful line in the document>

## Confidence

<high | medium | low, and what is reconstructed rather than recorded>

5. File it predictably

Convention is docs/adr/NNNN-short-title.md, numbered sequentially, never renumbered. Check the existing directory and follow whatever is already there instead of imposing this one. If a prior ADR is now superseded, update its status and link forward.

Guardrails

• Never invent a rationale. If you cannot recover why an option was rejected, write "rejected; reason not recorded". That gap is information.
• Record the decision made, not the one you would have made. If you think it is wrong, say so separately — do not let it leak into the framing.
• "Revisit if" is mandatory. A decision with no stated expiry condition becomes permanent by accident.
• Mark reconstructed records as such. An ADR written months later from fragments is useful, but the reader must know it is archaeology.