Documenting Decisions So They Stop Getting Reopened

Teams that suffer from reopened decisions almost always have somewhere decisions are written. That is the puzzling part, and it resolves as soon as you separate two activities that get discussed as one.

"The decision was made and nobody can find it."

Recording and retrieving are different problems

Recording is a writing discipline: at the moment of deciding, state the outcome clearly. It is cheap, it is well understood, and most teams can be taught it in one session.

Retrieval is a different thing entirely: three months later, someone who was not present needs this decision, and the only thing they know is roughly what the topic was. They do not know the date, the channel, the project it was filed under, or the words used. Recording is a habit; retrieval is an interface, and teams that fix the first and not the second keep having the same argument twice a year.

What to write, and what to leave out

Leave out the discussion, the attendee list, and the background. None of it is consulted later, and its presence makes the record longer than anyone will read.

The fourth line is the one that does the work. Most reopening happens because a reader cannot tell whether a question is settled or merely currently answered. "Changeable by Priya, or with evidence that volume passed 5k events a minute" answers both questions at once, and it converts relitigation from a social negotiation into a factual test.

Why retrieval is the harder half

The core difficulty is a vocabulary mismatch. The decision was recorded using the words of the people who made it. The person searching uses the words of their current problem. Those rarely coincide.

Someone asking "can I send order updates through the events pipeline" will not find a decision recorded as "shared queue for order events, starting with checkout", because they used none of those terms. They will search twice, find nothing, and ask a colleague, who will tell them from memory. The record was perfect and it made no difference.

Structured logs help a little and do not fix this, because they still require the searcher to know which entry they want. The related failure in FAQs is covered in an internal FAQ that stays current.

The bar to clear

State the requirement as a test rather than a process: can a colleague who was not present ask "what did we decide about X, and why" in their own words, and get an answer with a source under it, without interrupting anyone?

That is what StandIn does with decisions. The decision you wrote into your brief is what your StandIn answers from while you are off: in your words, with a source under every answer, clearly labelled, and it never guesses. Someone asking in their own phrasing gets the decision that matches their question, plus the reasoning, plus who can change it. And when the decision genuinely was not recorded, it says so and names who to ask, which is a much better outcome than a confident guess about what the team probably decided.

Retrieval stops depending on the searcher's choice of words or on the author being awake. See how StandIn works.

Two habits that make it stick

Write it where it was decided. A second destination halves adoption. If the decision happened in a thread, the four lines go in that thread. If it happened in a meeting, they go in the notes for that meeting and are read aloud before the meeting ends.

The decider writes it, not a scribe. A note-taker records what was said; only the decider can state what was decided and under what authority. Delegating this is the most common reason a decision record turns into a summary of a discussion.

One optional third habit worth the effort: when someone reopens a decision, answer with the record rather than from memory. It teaches the team that the record is authoritative, which is what eventually makes people check it before raising the question.

Common Questions

How should we document engineering decisions?

Four lines at the moment of deciding: the decision, who made it and when, what was rejected and why, and who can change it. Write it where the decision happened rather than in a separate system, and have the decider write it.

Do we need a formal decision log?

Only if someone will maintain it and people will read it. A log adds a second write step, which is where most of them die. What matters is that the decision is retrievable by someone who does not know how it was worded.

Why do people keep reopening settled decisions?

Usually because they could not find the original and are asking in good faith. A smaller share is genuine disagreement, and writing down who can change a decision handles both: the first group finds it, the second group knows what would justify revisiting it.

How much detail should a decision record have?

Enough that someone who was not there can act on it, which is usually four short lines. Longer records are less likely to be read and no less likely to be reopened, because length is not what makes a decision findable.