You Made the Call but Forgot Why — How to Write a Decision Record

"Wait, Why Did We Decide That?"

Six months ago, a meeting reached a clear conclusion: go with option B instead of option A. But now, looking back at that decision, nobody remembers why it was B. So the already-rejected option A gets pulled back out, and the same meeting happens all over again — a debate you settled months ago, restarted from scratch. It's what happens without a single decision record.

This isn't a problem of failing to decide. The decision was made. The problem is that the reasoning evaporated. The meeting notes preserved one line — "decided on B" — but "why B" and "why A was dropped" live nowhere.

This post covers where, when, and what to put in a decision record, and splits it into two cases: sharing with a team, and keeping it for yourself.

What a Decision Record Is

A decision record captures one decision together with the context, alternatives, and reasoning around it, on a single page. In software it's common enough to have earned its own name — ADR (Architecture Decision Record) — a sign of how essential the habit is there. But the idea itself isn't limited to architecture. Product direction, team policy, tool choice — it applies to any decision where "why we chose this" matters later.

The key is that it preserves the reasoning, not just the conclusion. Not only what you decided, but what the situation was, what you weighed, and why you landed where you did.

Why the Conclusion Alone Isn't Enough

Meeting notes usually keep the conclusion: "decided on B." But when only the conclusion survives, the most important part — the why — is missing.

As time passes and circumstances shift, the decision comes back up for review. Without the reasoning, you have to make the judgment call from zero again. Worse, a rejected option comes back like a zombie. Someone asks "what about option A?", nobody remembers why A was dropped, and it gets re-evaluated.

Keeping the reasoning ends that loop. If "A was rejected for these reasons" is written down, you only need to check whether those reasons still hold. You end up updating the decision rather than remaking it.

Where to Put It — Next to Where the Decision Resurfaces

There's one principle for choosing the location: keep it close to where the decision will be referenced again. A beautifully organized record filed somewhere far away is useless, because when the decision actually comes into question, nobody goes looking for it.

This is where team-shared and personal records diverge.

	Sharing with a team	Keeping it for yourself
Where	Somewhere the team looks daily — a shared wiki, an issue or ticket, a task description	Somewhere future-you will definitely open — a decisions note inside the project folder, a personal notebook
Format	Linkable — so meeting notes or tickets can point to it	Light — legible to you is enough
Purpose	"Whoever asks, this one link answers it"	"Just enough for the me of six months from now"

The specific tool isn't what matters. For a team, wherever the team already works; for yourself, wherever that work lives — the point is to keep it nearby.

When to Write It — While the Decision Is Still Warm

The timing principle is just as simple: write it right after the decision. Even a day later, the "why" starts to blur. You have to capture the page while the context is still vivid in your head for it to be worth anything later.

But you don't need one for every decision — that way lies burnout and abandonment. Write one only for decisions that are hard to reverse, or that will invite a "why did we do that?" later. Trade-off decisions are the classic case: choices where you gained something by giving something else up.

• Team: one page right there, at the meeting where the direction was set.
• Personal: one page before you proceed on that choice.

What It Actually Looks Like — Two Examples

Using the same skeleton (decision, context, alternatives, reasoning, status), here's how the container changes between team and personal.

Example A — Sharing with a Team

Situation: A meeting split over how many times to retry a failed payment.

Where: Create a decision ticket in the issue tracker, and link to it from the meeting notes. When: Right after the meeting ends.

What:

• Decision: Retry up to 3 times.
• Context: Timeouts on the payment provider's side were frequent, causing repeated failures.
• Alternatives weighed: Unlimited retries (dropped — risk of overloading the server), retry once (dropped — failure rate too high).
• Reasoning: 3 was the balance point between success rate and server load.
• Status: Active.

Two months later, a new teammate asks "why exactly 3?" — you hand over one link and you're done. No need to reconvene. If this decision ties into failure-handling policy, linking it to a document like timeouts and a retry policy keeps the context alive.

Example B — Keeping It for Yourself

Situation: Deciding, alone, what database to use for a side project.

Where: Create a single decisions note in the repository, right next to the project's description file. When: Before starting the first piece of work.

What:

• Decision: Use PostgreSQL.
• Context: Analytical queries are expected to be needed later.
• Alternatives weighed: A lightweight file-based DB (limited concurrency), a document DB (poor fit for relational data).
• Reasoning: It secures both relational structure and room to scale.
• Status: Active.

Six months later, when you wonder "why didn't I use something lighter?", the reasons you already weighed and rejected are written down, so there's nothing to reconsider. Even when you work alone, future-you is effectively a stranger — and you're leaving that stranger your reasoning.

What the two examples share is clear: the skeleton is identical; only the container differs. The team version sits in a linkable shared spot; the personal one sits in a light place future-you will open.

Don't Forget the Last Element — 'Status'

Of the five elements, the last one — status — matters more than it looks. Decisions aren't forever. They get superseded or retired. When that happens, updating the original record with a single line — "superseded by decision X" — turns it into a living history. Neglect the status, and an outdated record gets mistaken for current policy.

Building the habit of recording reasoning and history this way is the same grain as a closed-loop setup that lets you change rules without a deploy or reading an API spec so you draw the same picture as the developer. All of them share one principle: prevent later confusion with a record made now.

In Summary

A decision record isn't a grand document. One page is enough.

• What: Decision, context, alternatives weighed, reasoning, status — five things.
• Where: For a team, somewhere they look daily; for yourself, somewhere future-you will open. Next to where the decision resurfaces.
• When: Right after the decision, while the context is fresh. Only for decisions that are hard to reverse.

Keep only the conclusion, and six months later you repeat the same debate. Keep the reasoning too, and you update the decision instead of remaking it. Those differences add up — and both teams and individuals stop circling the same spot and actually move forward.

A record is a letter to your future self. Try leaving one page, so the you of six months from now can read today's judgment.