Decision Record

This is not a word invented by teams with no documents. Most teams had plenty. There is a product requirements document covering what to build and what counts as finished, a specification detailed enough to implement screen by screen, and a one-pager that compresses background and proposal onto a single page. All of them face forward. They are thorough about what will be built and silent about what was considered and dropped, and why.

The gap shows up about six months later. Someone who joined recently reads the code or clicks through a screen and asks why it works this way. The people who would know cannot answer precisely. One of the three who were in the room has left the company, and the two who remain remember the conclusion but not the counterargument. Searching chat turns up a thread, but the conclusion is somewhere in two hundred messages and it is not clear which channel the discussion actually ended in.

What this costs is not curiosity but hours. A person who cannot find the reason usually re-opens the decision from scratch. They surface an option that was weighed and rejected a year ago, present it as a good idea, another meeting gets scheduled, and the same reasoning produces the same conclusion. Once is waste; on a growing team the meeting comes back every quarter. With the decision erased, someone has to explain it from the beginning to each new face, and the explanation gets vaguer with every retelling.

A decision whose reason has vanished also hardens into a rule. A product policy — the document that pins down how the product must behave in specific situations — carries lines like "free plan users can create up to three documents." If nothing records where the number three came from, nobody will propose changing it to four. It might have been calculated from server costs at the time, or it might have been a round number somebody picked. When the two cannot be told apart, both become untouchable.

The damage runs the other way too. Decisions without recorded reasons are hard to revise. The assumption behind a call made six months ago may no longer hold, but if the assumption itself was never written down there is no way to check whether it still applies. So teams leave things alone rather than change them. A rule whose purpose is unknown is frightening to remove — and if something breaks after you remove it, you are the one who gets asked why you did.

A decision record answers both problems the same way. At the moment the call is made, while memory is still sharp, someone writes down what was decided, what was assumed at the time, and which alternatives were rejected for what reasons. That last item is the point. A document listing only the chosen option is what the requirements document already does; it is the rejected options and their reasons that let a future reader test whether those reasons still hold.

The definition-and-documentation strand of the product field holds nine documents, and they point in two directions. Release notes, which tell users what changed in a deploy, and the changelog that stacks that history in order both face outward. A decision record, like the one-pager, circulates internally only — and what most distinguishes it from the rest is that most of its readers have not joined the team yet.

Two terms sit under decision record, and both belong to one strand: format. They differ not in what gets recorded but in when during a decision they are used. One is written after the call has been made; the other is opened before it, to collect opinions.

1. Architecture decision record (ADR) — a short document capturing one decision about technical structure. The convention has settled into roughly four fields: what situation made this decision necessary, what was chosen, what follows from it, and whether the record is still in force or has been superseded. Length rarely exceeds one screen. The format was designed short on purpose, because a format that asks for pages produces nothing at all. Where it lives is unusual too. Teams typically keep ADRs as text files in the same repository as the code rather than in a document tool, so someone reading the code finds the reason next to it instead of in another system they would have to remember to search.
2. Request for comments (RFC) — a proposal that has not been decided yet, written up, published, and left open for comment for a fixed period. The name says it: this is a request for opinions, and its timing is the reverse of the first format. The author writes the background, the proposal, and the alternatives; anyone affected argues or adds in the comments; when the window closes the author writes the conclusion and closes the document. What this really does is pull dissent out of the meeting room. In a meeting the loudest voice and the most senior voice set the frame early, but a written objection reads at the same weight regardless of who left it. For teams spread across time zones the bigger win is finishing a decision without ever assembling everyone at once.

The two are not competing formats. They are the front and back of one decision. A large call starts as an RFC, gathers comment, and at closing time leaves a short record holding only the conclusion. A small call whose answer is already obvious is not worth an RFC and gets a record alone. Pagedeck draws the line at reversibility: changing the database, reworking the pricing structure, or picking where to host data opens an RFC, while choosing a library gets a single record.

The question that comes up next is how this differs from meeting notes. Notes follow the clock, so the conclusion has to be hunted for among everything else that was said, and anyone who was not in the room reads it without context. A decision record is scoped to one decision rather than one meeting. If a meeting settles three things, three records come out of it; if one decision took four meetings, it produces one record. That is why people search for these by the name of the decision, never by the date of a meeting.

What to record and what to skip is decided by the cost of reversing it. Changing a button from blue to green does not need a record, because an unpopular change ships back the next release. How data is structured, whether billing charges per seat or per usage, which region holds the servers — reversing any of those six months later means migrating accumulated data and existing contracts along with the code. Record only that class of call and roughly twenty documents accumulate in a year, which is few enough that a new hire can read all of them in their first week.

Adoption tends to follow a fixed order: settle the format, settle where records live, settle when to write them. The middle step is the one teams skip. However good the template, if each person files records somewhere different, nobody finds them a year later. A common arrangement keeps technical decisions in the code repository and product decisions in the product documentation folder, with one index page pointing at both. The third step lands as a habit rather than a rule. Reserving the last five minutes of a decision meeting for writing the record cuts down sharply on records that were going to be written later and never were.

"Does anyone know why this works this way? Is there a record for it?"

A check for whether the thing about to be changed has a reason attached.

"Let's open an RFC on this one. Comments until Wednesday, then I'll leave just the conclusion as a record."

The call is hard to reverse, so the objections are being collected up front.

"If the decision changed, don't edit the old record — write a new one and mark the old one superseded."

The value of a record is in how the thinking moved, not in the current state.

At Pagedeck this comes up most in a new engineer's first few weeks. Theo was walking a colleague who joined a month ago through a piece of code and ran out of answer. Nobody knew exactly why documents were stored split across two places. Digging through the repository turned up a record from a year and a half earlier with one line saying the storage service in use at the time could not accept large files, and another line saying to undo the split once that limit lifted. The limit had lifted eight months before. Without the record, that structure would have survived for years with nobody knowing why.

Mia added a rule after that: when a record states an assumption, it should also state the condition under which the assumption breaks. Grace looks at the same thing as spending. Writing a record costs twenty minutes; the meeting reopened because nobody wrote one costs five people an hour. She does not ask for everything to be recorded, though. Record reversible calls too and documents pile up faster than anyone reads them, which just adds one more drawer nobody opens. The line agreed in that meeting was to record only decisions that would take two people more than three days to undo.

The most common mistake is counting meeting notes or a chat thread as a record. Words exist somewhere, which sounds close enough, and sometimes everything needed really is in there. The problem is retrieval. Someone looking for a reason a year later does not know when the discussion happened or which channel it happened in, and does not know which words to search for. Left alone, this produces a team that believes it has documentation and a new hire who can find none of it, and the decision gets re-litigated anyway. Half the reason for keeping records separately is not what they contain but that they sit somewhere findable. For the same reason these documents get titled differently from notes: not "February 14 meeting" but "decision to consolidate document storage," phrased with the words a future searcher would actually think of.

The second mistake is editing the old record when a decision changes. Leaving a document that contradicts current reality feels sloppy, so bringing it up to date sounds obviously right. But the usefulness of this document is not in telling you what is true now. The code and the screens already do that. The question it answers is why a different choice once made sense and what changed. So a reversed decision gets a new record, while the old one keeps its text and gains a superseded marker plus a pointer forward. Start overwriting and two years later all that survives is a description of the present, and the mechanism built to stop debates from repeating no longer stops them.