Decision Records: 31 Decisions in One Quarter and What They Changed

Thirty-one decisions were written down in a quarter by a team that had never kept a record, and 12 of them were reversed within the same quarter. The reversals were the useful part. Each one had a stated reason, which meant the team could see what it had been wrong about.

The team ran infrastructure for a mid-size retailer with 60 engineers. Decisions were made in chat, in calls and occasionally in a document that nobody linked to.

The problem with verbal decisions

A decision made in a call survives as a memory in the heads of the people who were there. Six months later, a new engineer asks why a service is deployed a particular way and gets three different answers, all confident.

The team counted eleven occasions in one month where two engineers described the same decision differently.

The record format

The format was six lines: the decision, the date, the decider, the options considered, the reason, and what would make the team revisit it. Six lines fit in a chat message, which mattered more than any template.

The revisit line was the innovation. It converted a decision from a fact into a hypothesis with an expiry condition.

The first month

Eight decisions were recorded and about the same number were not, because people forgot under time pressure. The eight that were written took a median of four minutes each, most of them after the decision had already been made verbally.

Writing after the fact turned out to be fine. The value sat in the options list, not the timestamp.

The reversals

Twelve of the 31 decisions were revisited within the quarter. Nine were reversed because the condition named in the revisit line had occurred, which is the system working as designed. Three were reversed for reasons nobody had anticipated, which is the system being honest about its limits.

In both cases the record prevented the argument from restarting at the beginning. The discussion began at the point where the earlier reasoning stopped.

What the records did not capture

Politics did not make it into the records. Two decisions were driven by a deadline that came from a client, and the stated reason described a technical trade-off instead. The record was accurate and incomplete, which is a distinction the format cannot enforce.

One engineer pointed this out and was told the record was not a diary. That answer was accepted and is probably the right one.

The maintenance cost

Keeping records adds about four minutes per decision and roughly twenty minutes a month of tidying, since records accumulate in one folder and need an index. The index is a single page listing decision titles by date.

Without the index the folder becomes unreadable in about six weeks. The team learned this by letting it happen.

Two quarters on

The count of occasions where two engineers described the same decision differently fell from eleven a month to two. Onboarding questions about why something is built a certain way are now answered with a link.

Where the records sit

The records live in one folder with a single index page, because the search box in the team’s workspace does not rank by recency and returns the oldest record first. The index is a table with three columns and no ownership, which has survived because it is boring to maintain and easy to append.

Two records were written into the wrong folder in the first month and were found by accident. Nothing was lost, and the team now checks the folder count against the index once a month.

Who is allowed to decide

The decider field forced a question the team had avoided: for most decisions there was no single decider, only a conversation that ended. Writing a name in the field required someone to accept responsibility after the fact, which two engineers refused on principle.

The compromise was to allow a role rather than a name, such as platform lead. It weakens the record slightly and it made people willing to sign.

Thirty-one decisions in a quarter once produced twelve reversals and no explanation. The same reversals now carry a stated reason, and the next engineer who disagrees starts from the options rather than from nothing.