What Belongs in a Decision Record

The four-line entry is the floor: what, why, what was rejected, what would change it. This is what each of those lines has to actually contain to be worth writing — and the five things people put in instead that make a record longer without making it useful.

The six fields that earn their place

1 · The decision, as a commitment. One sentence, in the indicative. "The invite limit is 20." Not "we discussed invite limits and leaned toward keeping it low." A record that describes a conversation rather than stating an outcome cannot be checked against later, which means it cannot settle anything.

2 · The forcing question. What were you actually deciding? Surprisingly often absent, and without it the record is unreadable in a year — "the invite limit is 20" answers a question nobody wrote down, so a future reader cannot tell whether their situation is the same one. One line: "How many people can a workspace invite before we need billing to support it?"

3 · Why — the constraint, not the preference. "Because the seat model can't express per-seat proration above the plan cap" is a constraint: falsifiable, checkable, and it either still holds or it does not. "Because it felt cleaner" is a preference, which gives a future reader nothing to evaluate. If the real reason is a preference, say so plainly — an honest "no strong constraint, we picked one to stop debating" is more useful than a manufactured rationale, because it tells the next person the decision is cheap to change.

4 · What was rejected, with a reason each. One line per option. The reason is what does the work: "50 — billing can't invoice it" closes the question; "50 — rejected" reopens it.

5 · The revisit condition. "Revisit if we move to per-seat pricing." This is what converts a future argument into a check somebody can run in thirty seconds.

6 · Date and decider. Not for blame. For staleness — a decision from three quarters ago is a different object than one from last week — and so the next person knows who to ask when the record is thinner than they need.

What does not belong

The discussion transcript. Nobody reads it, including you. The conclusion and the constraints are the durable part; the path the conversation took to get there is not.

Options nobody seriously considered. Listing five alternatives when two were real makes the record look thorough and costs every future reader the time to work out which three were padding.

Implementation detail. How it gets built belongs in the spec. A decision record that drifts into schema design is doing a different job badly.

Hedging dressed as a revisit condition. "We may want to revisit this later" is not a condition. It is a sentence that permits reopening at any time for any reason, which is the state you were in before you wrote anything.

Consensus theatre. The list of everyone who agreed. It makes the decision harder to change — reversing it now looks like overruling eight people rather than responding to a changed constraint — and it records social fact rather than reasoning.

Status is what makes it a log

One field turns a pile of notes into something navigable: proposed / accepted / superseded by X.

The superseding is the point. When the limit moves from 20 to 50, you do not edit the old entry — you mark it superseded and write a new one that says what changed. Both stay. A reader arriving next year sees the path: it was 20 because of billing, billing shipped proration in June, it is 50 now.

Edit the original and you have current-state documentation, which cannot answer the question you needed.

What is worth recording at all

The most common way a decision log dies is trying to record everything. The second most common is recording nothing because the bar felt high. One test resolves both:

Could somebody reasonably propose the opposite, and would you have to explain why not?

If yes, record it. If the decision was obvious to everyone involved and nobody would argue it, skip it — you are not building an archive, you are pre-writing the answers to arguments you are going to have again.

In practice this is a handful of decisions per quarter, not a handful per week. Most of what a product team decides is uncontroversial execution. The ones worth the four lines are the ones that closed an option — where a real alternative existed and you chose against it.

What to keep from ADRs, and what to drop

The convention comes from engineering — a short append-only note per architectural decision, in the repo, with a status. It has survived for over a decade, which is unusual for a documentation practice, and the reason is that it is small.

Keep: append-only, the status field, the rejected-options section, and storage next to the work.

Drop: the numbering formality, the review-and-approve step, and the rigid context/decision/consequences headings if they slow you down. Product teams that adopt the full ceremony reliably abandon it in a quarter, and then conclude the idea does not work — when what did not work was the process wrapped around it.

The format is worth borrowing. The bureaucracy is not.

Who you are writing for

Not your team today. They were in the room; they do not need the record.

You are writing for one specific person: someone in eight months who has the opposite instinct and is about to act on it. Possibly a new hire. Possibly you, having forgotten.

That reader changes what you write. You are not summarising a meeting — you are making a case to somebody who currently disagrees with you and cannot ask you why. Which means the record has to do one of two things honestly: convince them the decision still holds, or give them enough to correctly overrule it.

Both are wins. A record that only does the first is advocacy; a record that does neither is a note to yourself you will not read.

FAQ

Do product teams need ADRs? The format transfers well; the ceremony usually does not. Keep append-only, status and rejected options; drop the numbering and the approval step.

Which decisions are worth recording? The ones that closed an option — where someone could reasonably propose the opposite.

What should it leave out? Transcripts, padding options, implementation detail, hedging, and the list of who agreed.

Why a status field? Superseding preserves the path. Editing the entry deletes the part that answers "why not the other thing".