The decision log every operator should keep

Most companies have no institutional memory of why things are the way they are. When the person who made a decision leaves, the reasoning leaves with them. A decision log — not a changelog, not a Confluence page, but a specific kind of record — is the lowest-overhead way to build institutional memory that makes a company faster to operate.

The problem with how decisions get recorded today.

In most companies, decisions are recorded in three ways, none of which captures what actually matters. The first is the Slack thread, which preserves the conversation but loses the conclusion. Six months later, no one can tell which thread represents the actual decision and which represents the thinking that preceded it. The second is the Confluence page or Notion doc, which captures the output of the decision — the policy, the process, the architecture diagram — but not the reasoning that produced it. The third is no record at all, which is the most common: the decision was made verbally, in a meeting or a corridor conversation, and lives only in the memory of the people who were present.

When a new engineer joins and asks why the data pipeline is structured the way it is, the only person who can answer is the engineer who built it. When a new sales hire asks why the company does not sell into a particular industry vertical, the only person who can answer is the founder who decided that three years ago. When a junior product manager asks why a particular feature works the way it does, the answer is "it has always worked that way" — which is a description, not an explanation.

This is not a documentation problem. It is an institutional memory problem. The distinction matters because the solution is different. Documentation is a writing discipline. Institutional memory is a retrieval discipline. The goal is not to write more — it is to make the reasoning behind consequential decisions retrievable by people who were not in the room.

What a decision log is and is not.

A decision log is a specific format for recording a specific kind of information: the reasoning behind consequential decisions at the time those decisions were made. It is not a changelog — a changelog records what changed, while a decision log records why. It is not a meeting notes document — meeting notes capture discussion, while a decision log captures conclusions and the logic behind them. It is not a strategy document — strategy documents describe where you are going, while a decision log describes why specific choices were made along the path.

The format of a decision log entry is minimal by design. If the format requires significant effort to complete, it will not be maintained. A useful entry has six fields.

Date. When the decision was made, not when the entry was written.

Decision. A single sentence statement of what was decided. "We will not build a native mobile app in the next twelve months." "We will price the enterprise tier at $2,000 per month, not on a per-seat basis." "We will use a PostgreSQL database rather than a document store for the core data model." Concrete, specific, attributable to a moment.

Context. Two to four sentences describing the situation that made this decision necessary. What was the trigger? What were the constraints? What did we know at the time that shaped the options?

Options considered. A brief list of the alternatives that were seriously considered and rejected. Not every option that was theoretically available — the two or three that were real candidates. This is the most important field. The reasoning behind a decision is only fully legible when you can see what else was on the table.

Reasoning. Why the chosen option was selected over the alternatives. What criteria were applied? What assumptions were made? What risks were accepted? This is the field that makes the log valuable — it is the context that prevents a future team member from revisiting a decision without understanding why it was made the way it was.

Revisit conditions. Under what circumstances should this decision be reconsidered? "If mobile usage exceeds thirty percent of our active user base." "If a competitor launches at sub-$500 per month pricing." "If we add a second database engineer to the team." This field turns the log into a living document — it tells future readers not just why the decision was made but what would make it the wrong decision.

The decisions that belong in the log.

Not every decision belongs in the decision log. The overhead of logging every choice — what to name a variable, which Slack channel to use for announcements — would make the log unusable. The decision log is for consequential decisions: ones that will be visible in the company's structure, product, or operations for more than six months, and ones that involve real trade-offs between legitimate alternatives.

The practical test is two questions. First: if a new team member encountered the outcome of this decision without context, would they likely wonder why things are this way? If yes, it belongs in the log. Second: if the person who made this decision left the company tomorrow, would the reasoning leave with them? If yes, it belongs in the log.

The categories of decisions that almost always qualify: architectural decisions about the technology stack, pricing and packaging decisions, go-to-market decisions (which channels, which segments, which partners to pursue or avoid), product decisions about scope (what the product deliberately will not do), hiring decisions about functional priorities (when to hire a head of X versus a senior IC), and process decisions about how the company runs (the operating cadence, the planning process, the performance review format).

The operational value compounds over time.

The decision log is useless in week one. In month six, it has prevented two or three instances of work being done that had already been done and rejected. In year two, it has saved multiple rounds of re-litigation of foundational decisions during leadership transitions, board conversations, and new hire onboarding. The compounding is slow at first and then sudden.

The most common moment when the decision log proves its value is the moment a new leader joins a team and immediately wants to change something that was deliberately designed the way it is. Without a decision log, the explanation for why things are the way they are is fragile — it depends on the memory of whoever was in the room when the original decision was made, and it is easily overridden by a confident newcomer who does not know what they do not know. With a decision log, the reasoning is available. The new leader can read it, evaluate it against current conditions, and make an informed choice about whether the original reasoning still applies. That is a qualitatively different conversation.

The second moment is the one that follows a key departure. When a co-founder leaves, or a long-tenured head of product departs, the institutional memory they carry is substantial and mostly tacit. They know why the pricing model was designed the way it was, why the product does not have a certain feature, why the company chose to focus on one segment over another. Without a decision log, that knowledge is gone. With one, the successor can access the reasoning that shaped the decisions they are inheriting — and make better decisions about which ones to honour and which ones to revisit.

The discipline of logging decisions at the moment they are made.

The decision log is only as good as the discipline of logging decisions contemporaneously — at the moment they are made, not six months later. Retrospective logging is useful for starting the log, but the detailed reasoning that makes an entry valuable is most accessible in the moment of the decision. A week later, the options that were seriously considered and rejected have already started to compress in memory. A month later, the uncertainty that surrounded the decision has been rationalised away. The entry written in the moment has texture that the retrospective entry lacks.

A practical implementation that works is a standing fifteen-minute block at the end of any meeting in which a consequential decision was made. The decision-maker fills in the entry before closing their laptop. Not a summary document, not meeting notes — the specific six-field format, written while the reasoning is still present. It takes fifteen minutes at most. The cost is negligible. The payoff is compounding.

The alternative — a standing reminder to log decisions before the end of the week — works less reliably. The reasoning degrades faster than most people expect. The half-life of the mental state that produced a decision is measured in hours, not days. Log it the same day or accept that you are logging a reconstruction rather than a record.

Where to keep it.

The decision log should be accessible to everyone in the company and searchable. It should not be buried in a project management tool where it requires knowing the project context to find. The formats that work are: a dedicated Notion database with fields matching the six-field format, a dedicated directory of short markdown files in the company's internal documentation repository, or a dedicated shared document with a table of contents sorted by date and tagged by function. The format matters less than the accessibility and the convention that everyone knows where it is and why it exists.

One anti-pattern to avoid: the decision log that lives with the founder and is not accessible to the team. The purpose of the log is to make reasoning accessible to people who were not in the room. A log that only the founder can access serves only one purpose — the founder's own memory — and misses the primary value, which is institutional knowledge that survives the departure of any individual.

• 01
  Log decisions at the moment they are made, not after. The reasoning that made a decision correct is most accessible the same day. A week later it has compressed. A month later it has rationalised. The fifteen minutes spent logging a decision contemporaneously is worth more than an hour of retrospective reconstruction. Build the habit before you need it — the log is useless in a crisis if it was not maintained in calm.
• 02
  Always log the options you rejected, not just the option you chose. A decision log entry without the alternatives is a record of a choice without the context that makes the choice legible. The rejected options are the most important part of the entry — they show future readers what the decision was actually between, and they prevent the trap of assuming that the chosen option was obvious.
• 03
  Include revisit conditions in every entry. Every significant decision rests on assumptions about the world that may change. Making those assumptions explicit — and naming the conditions under which the decision should be reconsidered — turns the log from a historical record into an active operating tool. A new team member reading an entry with revisit conditions knows not just why the decision was made but when it becomes their responsibility to question it.
• 04
  Make the log searchable and accessible before you need it. The decision log earns its value when it is consulted, not when it is written. A log that sits in a folder that new team members do not know exists provides no institutional memory benefit. Introduce the log as part of onboarding. Link to it from the company wiki's front page. Make it the first resource pointed to when a new team member asks "why do we do it this way?"
• 05
  Start with a retrospective batch if you are beginning now. If you are reading this and your company has no decision log, spend three hours identifying the fifteen decisions that most frequently require institutional knowledge to explain, and write retrospective entries for each. They will be less precise than contemporaneous entries, but they will capture the substance of the reasoning and immediately provide value to anyone who consults them. Do not wait for a clean starting point. Start with what you know now and log everything new from today forward.
• 06
  Review the log at leadership transitions, not just when building it. When a new leader joins — a new VP of Engineering, a new head of Product, a new co-founder — walk them through the decision log as part of their first month. Not to constrain them, but to orient them. The leaders who make the most destructive early decisions are the ones who do not know what they do not know. The decision log surfaces the hidden context that prevents well-intentioned people from dismantling things that were deliberately constructed.

Frequently asked questions.