Decision Log: How to Record Decisions So the Reasons Survive

Ask a team why a policy exists and you often hear a pause. Someone remembers a meeting. Someone else thinks it was a supplier issue. The person who knew left last year. The decision survived. Its reasons did not.

This is ordinary, and it is expensive. Without the reasons, a team has two poor options: keep a decision it no longer understands, or reverse it and risk bringing back the problem it solved. A decision log offers a third. Read the record, check whether the conditions still hold, and decide again on purpose.

Why organisations forget why they decided

Three forces work against an organisation's memory of its own decisions.

• Reasons live in conversations. Decisions are made in meetings, calls and message threads. The outcome reaches a policy or a plan. The context rarely does.
• People move. The people who weighed the options change roles or leave. Their understanding goes with them.
• Memory rewrites itself. In a 1975 study, psychologist Baruch Fischhoff found that once people know an outcome, they judge it as more predictable than it was. He called this "creeping determinism." After the fact, a sound decision that turned out badly looks careless, and a lucky one looks wise.

The last point matters most. Even when the same people remain, their memory of why they decided is shaped by what happened next. Only a record written at the time preserves what was known, what was expected and what was uncertain.

Microsoft's architecture guidance states the cost plainly. A decision that is never recorded "will likely be forgotten, leading to repeated debates."

What software teams learned: the architecture decision record

Software engineering has a well-tested answer. In November 2011, Michael Nygard proposed the architecture decision record, or ADR: a short document for each significant decision, numbered in sequence and kept with the project. His format has five parts.

• Title. A short noun phrase with a number, such as "ADR 9: LDAP for Multitenant Integration."
• Context. The forces at play: technical, political, social and local. Nygard asked that this section be value-neutral, a description of facts.
• Decision. The response to those forces, in full sentences in the active voice: "We will…"
• Status. Proposed, accepted, deprecated or superseded, with a reference to any replacement.
• Consequences. The resulting context. In Nygard's words, "All consequences should be listed here, not just the 'positive' ones."

The practice spread. Thoughtworks placed lightweight ADRs in the Adopt ring of its Technology Radar, its strongest level of recommendation, and advised keeping them in source control rather than a separate wiki. Microsoft's Azure Well-Architected Framework calls the decision record one of a solution architect's most important deliverables. Its guidance adds two rules worth borrowing: treat the log as append-only, and record a confidence level with each decision.

None of this is specific to software. Hospitals change admission procedures. Schools change assessment policies. Agencies change suppliers. Each of these decisions has context, options and consequences, and each will be questioned later by someone who was not in the room.

What a decision record should capture

A decision log is the collection of these records, with an index that summarises each one. Microsoft's engineering playbook describes the log as a table of executive summaries, with metadata, for the decisions held in the full records. The decision log template below works well beyond engineering. Each field earns its place.

• ID and title. A number and a phrase that states what was decided.
• Date. When the decision was made, not when it was written up.
• Owner. The person accountable for the decision, and who was consulted.
• Context. The problem, the constraints and the forces in tension.
• Options considered. Including those rejected, and why. This is the field most often missing and most often needed.
• Decision. One clear sentence that begins "We will…"
• Evidence. Links to the data, reports, audits or feedback the decision relied on.
• Expected outcome. What should be true if the decision works, and by when.
• Confidence. High, medium or low, with a line on what remains uncertain.
• Review date. When the decision will be checked against its expected outcome.
• Status. Proposed, accepted, superseded or retired, with a link to any replacement.

The expected outcome and confidence fields do the work of a decision journal. They record what you believed before you knew the result, which is exactly what hindsight erases.

We hold our own product decisions to the same habit. What was observed is written apart from what is inferred, and conflicting views are kept, not smoothed over. A decision deserves at least that much care.

Link each decision to its evidence and its outcome

A record that stands alone is better than nothing. A record that is linked is far more useful.

Link back to the evidence. When a decision cites a patient survey, a cost analysis or an incident report, link the source itself. Later readers can then judge whether the evidence still holds. Microsoft's guidance makes the same point: a record without justification "loses its value over time."

Link forward to the outcome. On the review date, write what actually happened next to what was expected. If the gap is large, ask why. Was the evidence weak? Did conditions change? Was the decision sound and the result simply unlucky? The answer is a lesson, and it belongs in the same chain. Our article on lessons learned that change the next project sets out how to make such lessons stick.

Link across to successors. When a decision is reversed, do not edit the old record. Mark it superseded and point to the new one. The history of a change in direction is often the most valuable thing in the log.

A hypothetical example shows the chain. A clinic decides to move follow-up calls from nurses to a dedicated coordinator. The record cites call-completion data, names the operations manager as owner, expects completion to rise within three months, and sets a review date. At review, completion has risen, but nurse workload has not fallen as expected. A new record supersedes the first, adjusts the role, and links back to it. Two years later, a new manager can read the whole story in five minutes.

Keep it light enough to last

Decision logs fail the way most documentation fails. They become a chore, and then they stop. Five rules keep them alive.

• Record only significant decisions. Microsoft's test is useful: decisions that shape the structure, affect key qualities, or are hard to reverse.
• Keep each record short. One page or less. Link to supporting material instead of copying it.
• Write it when you decide. A record written the same week is accurate. One written months later is a reconstruction.
• Keep it where the work is. A log kept beside the plans and procedures it affects gets read. A log in a separate folder does not.
• Start now, then backfill a few. Begin with new decisions. Then reconstruct the handful of past decisions people ask about most, and mark them as reconstructed.

A decision without its reasons is an instruction. A decision with its reasons can be tested, kept or changed with care.

How Prism keeps decision records

Prism holds an organisation's decisions and knowledge as items with a stated trust level: ratified, evidenced, observed or inferred. Each decision links to its evidence, to the steps that carry it out, and to the outcomes and Pause and Learn lessons that follow. When a decision is superseded, the earlier one stays visible. The assistants your team already uses can read the record too, so the reasons are there when someone asks. People make the decisions. Prism keeps their reasons.

Sources

1. Documenting Architecture Decisions. Michael Nygard, Relevance (now Cognitect) blog, 2011.
2. Architecture decision record (Azure Well-Architected Framework). Microsoft Learn, 2024.
3. Decision Log (Code-With Engineering Playbook). Microsoft, 2024.
4. Lightweight Architecture Decision Records (Technology Radar). Thoughtworks, 2018.
5. Hindsight ≠ foresight: The effect of outcome knowledge on judgment under uncertainty. Journal of Experimental Psychology: Human Perception and Performance 1(3) (B. Fischhoff), 1975.

Comments

Your nameYour comment

Comments appear after our team reads them. Please do not include patients' or colleagues' personal details.

Post comment