What does a decision record owe you?

Every recommendation we deliver ships as a decision record, so we have opinions about what the form owes its reader. The template is old and light; Michael Nygard's 2011 formulation fits on a page: context, decision, consequences. Most records we encounter in the wild pay the first two debts and skip the ones that mature later.

Which debts come due years later?

The consequences section, written without varnish, is a list of prices the team agreed to pay: "we accept eventual consistency on the activity feed," "we accept that reporting queries wait for the replica." Two years on, when a new engineer asks why the feed lags, the record converts an archaeology expedition into a paragraph. Records without consequences read like press releases, and press releases age like press releases.

The debt almost nobody pays is the reopening condition: what observable fact would make us revisit this? "We chose one region; revisit if the EU pipeline closes or p95 from Frankfurt exceeds 300ms." A record with a reopening condition is an instrument that watches the world. A record without one is a plaque, and plaques have a failure mode: they make old decisions feel settled precisely when the facts beneath them have moved, the multi-region question being a recurring example.

What does the record owe the dissent?

A fair hearing on paper. The options-considered section is where most fiction enters: alternatives get recorded as strawmen so the chosen path looks inevitable. The tell is an options list in which every rejected option has zero stated advantages, a pattern with the evidentiary value of an election won 100 to 0. We ask teams to write the strongest case for the road not taken, one honest paragraph, because the future reader most likely to open the record is the one about to propose exactly that alternative, and the record either meets them with reasoning or meets them with attitude.

Dissent recorded is also cheaper than dissent suppressed. A line reading "the data team preferred option B for warehouse compatibility; we proceeded with A and accepted the export tax" costs three minutes and prevents the same argument from being held annually, a service the incident folder cannot provide.

What would have to be true for records to stay written?

The practice survives where records are load-bearing: linked from the code they govern, checked in reviews ("does this change contradict ADR-31?"), and written for decisions of consequence only. It dies where it becomes ceremony, forty records deep in a quarter, none reopened, none read. Our threshold suggestion: if reversing the decision would cost more than a sprint, it earns a record; below that, the pull request description suffices.

The form is humble and the return is not. A shop with three years of honest records can answer "why is it like this" without convening the elders, which is what institutional memory means when it is actually funded. The record owes you context, prices, a fair fight, and a tripwire. Collect all four.