How to Document Decisions So They Actually Stick (and Stop Getting Re-Argued)

Eleven months ago your team spent three meetings choosing between building the integration in-house and buying it. People came prepared. Somebody made a spreadsheet. The discussion was genuinely good — concerns were raised, trade-offs weighed, a call was made. Then everyone went back to work.

This week a new engineering lead joined, looked at the integration, and asked the reasonable question: "Why didn't we just build this ourselves?" And the honest answer available to anyone in the room was: nobody remembers exactly. So the question is open again. The three meetings are about to happen again — with less information than the first time, because the person who made the spreadsheet left in March.

Nothing about that story is unusual, and that is the problem. Teams that would never lose a task lose decisions constantly, because tasks have a system and decisions have a vibe. This post is the complete, practical fix: what to write down, the seven fields that matter, the frameworks worth borrowing from, and the habits that make the practice stick.

What a Decision Record Is — and What This Post Covers

A decision record is a short, structured document capturing one significant decision: what was decided, what the alternatives were, why this option won, who owned the call, and when you'll check whether it worked. It is written when the decision is made, not reconstructed later, and it lives somewhere the whole team can search.

It is not meeting minutes — a chronological account of a conversation — and it is not a task. Those distinctions matter enough that each has its own post: meeting minutes vs. the decision log covers the document level, and action items vs. decisions covers the task level. This post is the how-to that both of them point back to.

One scope note: significant decisions. Where to hold the offsite does not need a record. Anything you'd hate to re-argue in six months — architecture, vendors, pricing, policy, hiring bars — does. A useful test: if a future colleague could plausibly ask "why is it like this?", the decision qualifies.

What Undocumented Decisions Actually Cost

The costs are mundane, recurring, and mostly invisible because they arrive disguised as normal work. Settled questions get re-litigated — the same debate, staged again, minus whoever held the context. New hires inherit systems whose shape nobody can explain, so they either relearn by breaking things or route every question to the longest-tenured person in the room. And when an outcome goes wrong, there is no way to tell whether the reasoning was bad or the luck was — which means the process never improves.

There is also a sharper edge: accountability. When a decision exists only in memory, its history gets rewritten by whoever retells it — usually in their own favor. A record makes the reasoning inspectable when it matters, which is the foundation of a real decision audit trail. We wrote a short companion piece on the compounding cost itself: the cost of undocumented decisions.

The Frameworks That Already Exist — and the Gap They Leave

You don't have to invent this practice; several serious frameworks touch it. But it pays to notice what each one actually covers, because the most popular ones solve a different problem than the one this post is about.

Notice the pattern: three of the four famous frameworks assign roles; only ADR produces a record. Roles and records are complementary halves — RAPID or DACI tells you who has the D; the record preserves what the D decided and why. Most teams that feel "we have a decision process" have adopted a role framework and skipped the record entirely. That is the gap the seven fields below fill. One framework does straddle the line, and it is worth naming because it is the closest thing to a record that a role framework produces: SPADE (Gokul Rajaram, used at Google, Facebook and Square) adds Alternatives and Explain to the roles the others assign — two of the seven fields below, captured in the moment of deciding rather than afterwards. It still organises by decision-meeting rather than by decision, so it is not yet a log; but a team already running SPADE is two fields from one. The short version is the SPADE framework in five letters, and all four role frameworks sit side by side in the decision-rights guide.

What to Capture: The Seven Fields

This is Argumentree's own template — not an external standard, but a synthesis we use and recommend: ADR's record discipline, extended with the two things general team decisions need that architecture decisions get for free (an explicit owner, and a review date). Steal it as-is.

A Record You Can Copy

In practice the seven fields fit on half a page. A worked example, compressed:

That is the whole artifact. Anyone joining the team next year reads it in forty seconds and knows what was decided, what it beat, what it cost, and when it comes back up. Compare that with three meetings' worth of minutes.

The Practices That Make It Stick

Templates don't fail; habits do. Four practices separate teams whose decision logs live from teams whose logs die after week two:

The Common Mistakes

Four failure modes account for most abandoned decision logs:

"We're Agile — Isn't This Just Documentation Overhead?"

The strongest version of the objection deserves stating properly: documentation has a real cost, most documents are never read, and a team that spends its energy writing about work instead of doing it has made itself slower for nothing. Agile's insight — working software over comprehensive documentation — was a correction to a real disease.

The answer is that the objection targets the wrong artifact. Nygard wrote ADRs for agile teams, on exactly this reasoning: the record is half a page, written once, at the moment the knowledge is free — and its reader is not an auditor but future you, eleven months from now, staring at the integration and wondering why. The cost asymmetry is extreme: five minutes at decision time versus three meetings of re-litigation later. This is the rare documentation that pays for itself in avoided meetings.

The honest caveat: the practice does fail when it is imposed as process theater — mandated fields nobody believes in, records written to satisfy a checkbox. It works when the team has felt the pain it prevents. If your team hasn't lost a decision yet, start with the one log entry for your next significant call and let the first "wait, we wrote this down!" moment sell the habit.

How Argumentree Documents Decisions Automatically

Everything above works with a wiki page. The reason we built Argumentree is that the hardest field to capture manually is field 3 — the arguments — because they happen live, in discussion, and writing them down afterward means summarizing from memory. In Argumentree the deliberation itself is structured: the question is explicit, options and their pro/con arguments form a tree, and ratings show which arguments actually carried the decision.

Which means the decision record isn't a document someone writes after the meeting — it is the meeting's own structure, preserved. All seven fields fall out automatically: question, options, arguments, decision, rationale (the winning argument path), owner, and a review date. No transcription step, no memory drift, and the full reasoning stays inspectable for every future reader. See it end-to-end in meeting intelligence. If you want to try the format on a real decision this week, you can start free and document the next one as you make it.

Decisions Are an Asset — If You Keep Them

The difference between an organization that gets smarter and one that stays busy is not intelligence — it is memory. Tasks get done and evaporate; decisions, kept with their reasoning, compound: precedents form, patterns surface, and reviews teach the process to improve itself.

Start smaller than feels serious. Next significant decision: five minutes, seven fields, one searchable home, one review date. When the new engineering lead asks "why didn't we build this ourselves?" — and someone answers with a forty-second read instead of three meetings — the practice will have paid for itself, permanently.