top of page

Decision Record and Reversibility Worksheet

S. West
1 hour ago
5 min read

The team spent five weeks choosing a message queue. Six months later a new architect reopened the choice, and nobody could explain why it had been made.

A platform group compared two queues with benchmarks, a proof of concept for each and a fortnightly steering meeting. Meanwhile three feature teams built against a stopgap queue, which became the real one by default. When the decision memo arrived it named the winner and listed scores, but said nothing about the assumptions behind them. When the architect joined, there was nothing to check those assumptions against, so the analysis restarted from zero.

(Composite example, assembled from patterns common in engineering organisations that treat every technical choice as permanent. The figures are illustrative.)

Two things went wrong: a choice that could have been undone cheaply got a heavyweight process, and the record kept the answer but lost the reasoning. This worksheet starts from the reversibility end. You size the effort to how hard the choice is to undo, narrow the options, test the favourite against failure, and then write a record that a stranger could use to decide whether the call still stands. Most two-way doors need only Steps 1, 3 and 4, in one sitting.

Step 1: decide which door it is

Write the decision in one sentence:

Which door is it? (Jeff Bezos's one-way/two-way door distinction, from Amazon's 2015 shareholder letter.)

  • ☐ Two-way door: you can walk back through it, and being wrong costs rework. Examples: a test framework, a message queue, a deployment platform, a coding convention. Cap the analysis and decide quickly.

  • ☐ One-way door: reversal is slow, costly or impossible. Examples: the primary database once years of data sit in it, a cloud provider after deep use of proprietary services, a public API contract with outside consumers. This one earns more analysis.

Reversibility checks:

  • ☐ Could we undo this without a catastrophic cost?

  • ☐ Would an interface, adapter or other layer of indirection make it easier to undo? If so, some extra complexity may be worth paying.

  • ☐ Are we giving a two-way door a one-way-door process, such as a steering group for a CSS framework? If so, shrink the process now.

ShiftQuality's rule of thumb, not a measured result: treat week one of investigation as clearing most of the uncertainty (call it 80%), week two another 10% and week three another 5%. Once you're in that tail, extra research is buying delay, not knowledge.

Step 2: narrow the options

A. Frame the problem before anyone argues for a solution. Teams that deadlock often turn out to be answering different questions.

  • The pain we're removing: ______

  • The constraints we can't break: ______

  • How we'll know it worked: ______

B. Filter on hard constraints. Remove every option that fails one before you compare the rest.

Hard constraint

Options it rules out

______

______

______

______

______

______

C. Map the trade-offs for the options left standing. Writing them side by side stops one dimension, usually speed to build, from deciding everything.

Option

Strengths

Weaknesses and costs

______

______

______

______

______

______

______

______

______

D. Pre-mortem (Gary Klein's technique): "Assume we chose this and it failed. Why?" It brings out the risks that optimism hides.

  • It failed because: ______

  • The first warning sign we'd see: ______

  • What we'd do about it now: ______

Step 3: set a deadline and make the call

  • Decide by: ______ (without a date, teams hedge: parallel proofs of concept, split effort and, eventually, a default nobody chose)

  • The decision: ______

  • ☐ We have the input this decision needs, not every input we could collect.

  • ☐ The option is good enough to proceed, the date has held, and we know how we would back out.

Not deciding is often the costliest choice on the table, because you keep paying for every open option and collect the benefit of none.

Step 4: record the reasoning

The outcome is the name of the winner. The record is the case for it, written so that whoever inherits it can test the assumptions instead of redoing the analysis. This usually takes about fifteen minutes, and it can save hours of re-analysis.

(Adapted from Michael Nygard's Architecture Decision Record format. Add a Status line so superseded decisions stay findable.)

  • Title: ______

  • Status (proposed, accepted, superseded by ______): ______

  • Context (what forced the decision, and what was true at the time): ______

  • Options considered: ______

  • Decision: ______

  • Reasoning (why this one, and why not each alternative): ______

  • Assumptions it rests on: ______

Step 5: set review triggers

Reopen a decision when an assumption from Step 4 stops being true, not when a newcomer prefers something else. Each trigger should be specific, measurable and tied to a named assumption.

  • ☐ Trigger 1: ______ (assumption it tests: ______)

  • ☐ Trigger 2: ______ (assumption it tests: ______)

  • ☐ Trigger 3: ______ (assumption it tests: ______)

Illustrative shape: reopen the database choice if stored data passes 500GB or writes pass 10,000 operations per second. The thresholds are an example of the form, not a claim about any database's limits. Without triggers, a conference talk or a blog post is enough to put last quarter's call back on the agenda.

Step 6: close it

  • ☐ The record is stored where the team will look for it, such as an ADR in the repo.

  • ☐ Each trigger has an owner.

  • ☐ The decision has been announced, and the teams waiting on it know they can proceed.

If reality departs from the assumptions, correct course quickly. Otherwise the decision is made; stop reopening it.

How to use it

  • Who: the engineer or leader who owns the call, with one or two people who will live with it. Run it at a whiteboard; for a two-way door, keep it to one meeting.

  • Output: a door classification, a filtered option list with trade-offs, a pre-mortem, and a decision record with a status and named review triggers.

  • Done when: the record is in the repo, every trigger has an owner, and the teams blocked on the decision have been told to proceed.

Where this changes

A two-person team choosing a library can stop after Step 1 and a three-line record: what was chosen, why, and what would make you revisit it. A large or regulated organisation needs more for one-way doors: a named decision owner and approvers, a design review on file, and records kept as evidence. Shared roles help here, and the DACI decision framework sets them out. If you can't yet tell what kind of uncertainty you face, the Cynefin framework (Snowden and Boone, 2007) helps you choose between analysing and probing.

The reasoning behind this worksheet is in technical decision-making under uncertainty. To store the Step 4 output, use the Architecture Decision Record (ADR) template, and to run Step 2D with a whole team, see why pre-mortems beat post-mortems.

Final takeaway

Size the process to how hard the choice is to undo, then put a date on it. Record the reasons and the assumptions as well as the answer, and agree in advance what would make you reopen it.

Sources

bottom of page