Every working life is full of decisions that made perfect sense at the time. You chose this pricing structure, that tool, this client process, that naming convention. Six months later, someone asks why, possibly you, and the honest answer is a shrug.
The what survived. The why evaporated.
Software teams hit this problem early and hard, because codebases outlive the memories of the people who built them. Their answer was the decision record: a short, structured note written at the moment of choosing. The habit is just as useful for ordinary knowledge work, and much simpler than it sounds. This playbook shows how to borrow it.
Why does the “why” disappear?
Because decisions are made in conversations, heads and chat threads, and none of those are designed for retrieval. The decision itself usually ends up somewhere permanent: the price is on the website, the tool is in use, the process is running. The reasoning, the options you rejected and the constraints you were under, stays in the ephemeral layer and fades.
That loss has real costs:
- Relitigating. You revisit the same decision repeatedly because nobody remembers why it was settled.
- Accidental reversals. Someone “fixes” a deliberate choice because it looks like a mistake without its context.
- Lost learning. You can’t evaluate past decisions if you can’t remember what you expected them to do.
Where does the decision-record habit come from?
From several traditions, each solving the same problem of preserving reasoning.
Judicial opinions. Courts in common-law systems don’t just announce outcomes. They publish written opinions explaining their reasoning, so that later courts can follow, distinguish or overturn them. The reasoning, not just the verdict, becomes part of the record.
Minutes of meetings. When Henry Martyn Robert published Robert’s Rules of Order in 1876, it formalized, among much else, how organizations record their decisions in minutes. A motion, its outcome and the record of it give a group a shared memory that outlasts any individual member.
Architecture decision records. In 2011, software engineer Michael Nygard published a short post, “Documenting Architecture Decisions,” proposing that teams write brief records of significant decisions, each with a context, the decision itself and its consequences. The format spread widely because it was small enough that people actually used it.
The lesson from all three: reasoning survives only when it’s written down at the time, in a consistent format.
What goes in a decision record?
Five sections, each short:
- Context. What situation prompted the decision? What constraints applied? “Two clients asked for monthly retainers; our current pricing is per project only.”
- Options considered. What did you seriously consider? “Keep per-project only; add a fixed retainer; add a retainer with rollover hours.”
- Decision. What did you choose? “Add a fixed monthly retainer, no rollover.”
- Consequences. What do you expect to follow, good and bad? “Simpler billing and steadier income; some clients may want rollover and we’ll say no.”
- Links. What notes, projects or clients does this connect to?
Plus a little metadata: a date and a status of proposed, accepted or superseded. When a later decision replaces this one, the new record notes what it supersedes, and the old one is marked superseded rather than deleted. The history stays intact.
What does a finished record look like?
Here’s a short, fictional example for a solo content strategist, written the day the decision was made.
Title: Stop offering one-off blog posts Date: [decision date] · Status: accepted
Context. One-off post requests make up a large share of inquiries but require the same onboarding as larger engagements. Scheduling them around retainer work has caused repeated crunches.
Options considered. (a) Keep offering them at the current rate. (b) Raise the one-off rate to cover onboarding. (c) Stop offering one-offs and point inquiries to a minimum three-post package.
Decision. Option (c). Minimum engagement is a three-post package.
Consequences. Fewer small inquiries convert. Onboarding effort is spread across more work. Existing clients with open one-off requests are honored through the end of the quarter.
Links. Pricing concept note; Services hub; this month’s digest.
That’s under 150 words. It took a few minutes. And it answers, permanently, the question that will otherwise come back every time a tempting one-off inquiry arrives: “Why did we stop doing these again?”
Notice what makes it work. The context names the actual pain. The options include the one you didn’t choose but might be tempted to revisit, option (b). The consequences include the downside, so when fewer small inquiries convert, it reads as expected rather than alarming. And the links mean the record surfaces wherever the topic comes up.
How long should a record take to write?
Five to ten minutes. If it’s taking longer, you’re writing an essay. The point is to capture enough that a future reader understands the reasoning, not to justify the decision to a tribunal.
A useful test: could someone who wasn’t in the room read the record in two minutes and understand why you chose what you chose? If yes, it’s done.
Which decisions deserve a record?
Not all of them. Recording what you had for lunch is not a knowledge system, it’s a diary. A reasonable filter covers three kinds:
- Hard to reverse. Pricing structures, tools that hold your data, contractual terms.
- Likely to be questioned. Anything a client, collaborator or future you might ask “why?” about.
- Made with real tradeoffs. If you rejected a serious alternative, record why.
For most solo practitioners, that’s a few decisions a month. Enough to matter, few enough to sustain.
What’s a digest, and why pair it with decisions?
Decision records capture individual choices. A digest gathers them, periodically, along with everything else that changed. Think of it as a short newsletter to your future self, written weekly or monthly, with four sections:
- Highlights: what mattered this period.
- New notes: what you added to your knowledge system.
- Decisions made: links to this period’s decision records.
- Open questions: what’s unresolved and worth revisiting.
The digest solves a retrieval problem. Six months from now you won’t remember which decisions you made in March, but you can open March’s digest and see them all, in context, alongside what else was happening.
How do the two workflows fit together?
A simple rhythm:
- When a significant decision happens, create a decision record from the template. Status: proposed or accepted.
- Link it to the relevant project, client or concept notes.
- At the end of each week or month, write a digest. List the period’s decisions, new notes and open questions.
- When a decision changes, write a new record that supersedes the old one, and mark the old one superseded.
- Before revisiting a choice, search decisions first. Often the reasoning you need is already written down.
- Once a quarter, reread a few old records and compare their expected consequences with what happened.
Step six is where the habit pays the most. Comparing what you expected with what happened is how judgment improves. Without records, you can’t do it honestly, because memory quietly edits your old expectations to match the outcome.
What mistakes undermine the habit?
Six common ones:
- Writing records after the fact, when the reasoning has already been reconstructed.
- Skipping options considered, which is where most of the value lives.
- Deleting superseded records instead of marking them, which erases the history.
- Recording everything, until the habit becomes a chore and stops.
- Never linking records to the work they affect.
- Skipping digests, so records become a pile no one browses.
Does this work for teams of one?
Especially for teams of one. Teams at least have colleagues who remember. A solo practitioner’s only colleague is their future self, who has forgotten everything and is slightly annoyed about it.
What’s in the kit?
The Ontology & Knowledge-System Starter Kit includes ready-to-use Decision and Digest templates as part of its eight-template set, along with worked examples of both workflows. The Decision template has the five sections above, plus date, status and supersedes fields. The Digest template has Highlights, New notes, Decisions made and Open questions, with a period of week, month or source.
They sit inside a layered Obsidian vault (Core, Domain, Applied) alongside Concept/Class, Relation, Instance, Hub, Project Workbench and Daily templates, so decisions link naturally to the projects and concepts they affect. No plugins are required.
Quick answers
Do I need Obsidian?
The templates are Markdown, so they work in any notes tool. The vault is set up for Obsidian’s templates folder.
Should decision records be public to clients?
Usually not in raw form, but they make it easy to explain your reasoning when a client asks.
What if I made a decision long ago and never recorded it?
Write a record now, with what you remember, and note that it was written retrospectively. Imperfect reasoning on paper beats perfect reasoning lost.
Write down why
The decisions you make shape your work for years. The reasoning behind them is worth five minutes of writing. Future you will open a record, read the context, and nod instead of shrugging.
Get the Ontology & Knowledge-System Starter Kit and write your first decision record this week, about something you’d hate to relitigate.
You’ll find the Decision and Digest templates, and the rest of the vault, on Tools for Obsidian.
Leave a Reply