Decisions deserve their own data model
Ask any team why they chose their current database, their pricing model, or their authentication provider. Half the time, nobody knows. The person who made the call has left. The meeting notes are buried in a folder nobody opens. The Slack thread is lost in three years of scrolling. The decision exists as an outcome, stripped of everything that made it understandable.
This is not a memory problem. It is a data model problem.
Most organisations store decisions the same way they store everything else: as text. A bullet point in a meeting summary. A paragraph in a document. A message in a channel. Text is fine for capturing what was decided. It is terrible for capturing why, what else was considered, and what it means for everything that comes after. This is a problem that extends across all organizational knowledge, but decisions require a specific structural approach.
When you need that context later, it is gone.
The difference between an outcome and a decision
Here is a fact: “We use PostgreSQL.”
Here is a decision: “We chose PostgreSQL over MongoDB because our data has strong relational structure and our team has more experience with SQL. We considered MongoDB for its flexibility, but rejected it because the join patterns in our billing module are too complex. This means new features with non-relational data structures will require deliberate schema design.”
The fact tells you what is true. The decision tells you why it is true, what you gave up, and what it implies. Those are three entirely different things, and only the decision lets you reason about whether the choice still makes sense.
Most knowledge systems only store facts. That is why every organisation periodically re-debates decisions that were already made, re-evaluates tools that were deliberately chosen, and onboards new colleagues who spend months building intuitions that could have been handed to them in a five-field document.
What a decision actually is
A decision has five fields. No more, no less:
The five required fields
The question. What problem were you solving? What was the forcing question? Without this, the decision is floating in context-free space.
The decision. What was chosen? This sounds obvious but it often is not. “We decided to improve the onboarding” is not a decision. “We decided to add a mandatory product tour for all new signups” is a decision.
The rationale. Why this choice? One to three sentences. Not a full justification, but the core reasoning. This is the field most worth preserving and the hardest to reconstruct later.
The alternatives considered. What did you evaluate and reject? This is the most underrated field. Every time someone in the future evaluates an alternative you already dismissed, they are doing work your organisation already did. Documenting rejected alternatives means that work gets done once.
The consequences. What changes as a result? What commitments does this create? What future options does this close?
Five fields, three minutes to fill in. That is the whole model.
Why this is the hardest thing to capture
I want to be honest here: decision capture is the part of Klai Knowledge that we cannot automate. And I think you should know that before you read any further.
The AI limitation with decision rationale
AI can find decisions in transcripts with reasonable accuracy. It gets the “what” right about 60-75% of the time. But the rationale, the field that actually matters, almost never exists explicitly in text. People do not say “I am choosing PostgreSQL because of the following three reasons.” They talk through options, circle back, agree on something, and move on. The reasoning is implicit in the conversation, distributed across multiple speakers and multiple turns.
When AI tries to extract the rationale from this, it fills in the gap with something plausible. And plausible-but-wrong is the most dangerous type of error in a knowledge system. It reads like a real reason. It passes casual inspection. It gets stored and retrieved and treated as truth.
Why we chose the human-in-the-loop approach
We tested this extensively. The hallucination rate on rationale extraction was too high to ship. So we did not ship it.
What we built instead is a capture flow that removes friction from the human step. When a decision shows up in the knowledge system (a PR description, a design doc, a Slack thread, a meeting note), Klai surfaces a suggested draft pre-filled from the surrounding context. The draft gets the question and the decision roughly right. The rationale is a placeholder. A human fills in what actually happened and why, in two minutes, while the context is still fresh.
This is not a compromise. It is the correct design. The rationale has to come from the person who made the call. There is no shortcut around that.
What actually works: the moment of deciding
The pattern that works in practice is well-established. Software engineers have used Architecture Decision Records (ADRs) for over a decade. The principle is simple: capture the decision at the moment it is made, in a lightweight structured format, linked to the context where it happened.
Capture immediately, while context is fresh
Three minutes. Five fields. Done while the source is still open: the PR under review, the design doc in draft, the decision still fresh in your head.
AI as a draft assistant, not the decision maker
AI has a supporting role here that is genuinely useful: it can draft a first version based on the surrounding context. If a decision is referenced in a design doc or a PR description, the surrounding text gives the AI enough material to suggest a question, a decision, and a rationale. A human reviews it, corrects the rationale, adds the alternatives, confirms the consequences. The AI removes the blank-page problem. The human ensures accuracy.
This is the right split. AI accelerates the capture. Humans own the rationale.
The connections that make decisions valuable
A decision stored as a standalone document is more useful than a decision buried in meeting notes. But a decision connected to the rest of your knowledge base is a different thing entirely.
Decision as a first-class entity in your knowledge graph
In Klai Knowledge, a decision is a first-class entity that links to the other things in your knowledge graph. It connects to the people who made it (so you can ask who owns this). It connects to the project or container it belongs to (so you can see all decisions in a product area). It connects to the documents it affected (so you know what changed). It connects to the meeting where it was made (so you have the full context if you need it). And it connects to other decisions it superseded or depends on.
Decision dependencies surface risks automatically
That last connection is particularly powerful. Decisions have dependencies. “We chose React” depends on “we are building a web app.” “We moved to microservices” supersedes “we run a monolith.” When those upstream decisions change, the downstream ones need review. A knowledge system that tracks these relationships can surface that automatically. Without the connections, you have to rediscover them manually every time.
Why it is worth the effort anyway?
If this cannot be automated, why bother building it into a knowledge system at all?
Because the value of a captured decision compounds over time in a way that almost nothing else in a knowledge base does.
An article about how your return policy works becomes outdated the moment the policy changes. A decision about why you structured the return policy the way you did stays useful even after the policy changes, because it explains the reasoning behind the original choice and gives the next person the context to make a better revision.
There is a simple test for whether your decision documentation is working: how long does it take a new colleague to understand why the system is built the way it is?
If the answer is “months of asking around,” your decisions are not documented. If the answer is “a few hours reading the decision log,” you have it right.
The cost of not doing this is invisible until suddenly it is not. It shows up the first time a new engineer rewrites something that was deliberately built a certain way, not knowing why. It shows up in the meeting where you spend forty minutes re-evaluating an option that was dismissed eighteen months ago for good reasons that nobody wrote down. It shows up when the founder is the only person who knows why the pricing is structured the way it is, and then the founder is not around.
Three minutes per decision, at the moment it is made. That is the investment. The return is an organisation that can explain itself.
What you can do today
You do not need a dedicated system to start capturing decisions. Three things you can do this week.
Start with the next ten decisions your team makes
Do not try to backfill. Start from now. The next architectural choice, the next product direction, the next vendor selection. Five fields, three minutes. Build the habit before building the infrastructure.
Create a decision template
Copy the five-field structure into a Notion page, a Google Doc, or a shared folder. The simpler the format, the more likely people will use it. Friction is the enemy of this habit.
Link decisions to where they live
If a decision comes out of a PR review, link the decision record to the PR. If it comes out of a design doc, link it to the doc. If it comes out of a Slack thread, link the thread. Context is what makes decisions retrievable later. This is what transforms a decision from an isolated fact into part of your organizational knowledge graph.
Decisions are the connective tissue between what your organisation knows and what it does. An article tells you how something works. A decision tells you why it works that way, what else was considered, and whether it still makes sense. Without that layer, your knowledge base is a library of facts with no explanation of how they came to be true.
Start small. Pick the last significant decision your team made and try filling in the five fields. If you struggle to reconstruct the alternatives and the reasoning, you have just found exactly why this matters.
This is the last post in the “How an organisation learns” series. The next series, “Modelling knowledge”, digs into the data model that makes all of this work. Start with evidence vs. claims: the distinction that changes everything.