Two people on the same team remember the same meeting differently. One says the pricing tier was decided. The other says it was floated and never closed. Both are certain. Both are, in their own way, telling the truth, because what happened in that room was a conversation, and a conversation is not a record. A week later the feature ships against one interpretation and the other person says the sentence that costs product teams more time than any bug: “I never agreed to that.”
You cannot argue your way out of that. There is no artifact to point at. So the team relitigates a question it already answered, and the answer this time is shaped by whoever is more tired, more senior, or more recently annoyed. Multiply that by every non-trivial choice a product makes and you get a team that spends a third of its energy re-deciding things instead of deciding new ones.
The problem is a recording failure, not a memory failure
It is tempting to treat this as people being forgetful or political. Mostly it is neither. A decision is a moment. It happens in a Slack thread, a hallway, a call, a comment on a mockup. It is real when it is made and then it dissolves into everyone’s slightly different recollection. Nothing captured it, so there is nothing to disagree with, only each other.
This gets worse the moment agents enter the loop, and it is the core of what shifted in product management in the AI era. When building was slow, a fuzzy decision had days of engineering friction in front of it, and that friction was, accidentally, a review. Someone would ask “wait, did we decide this?” before it cost much. Now an agent turns a fuzzy decision into working code in an afternoon. The friction is gone. The half-remembered choice becomes a shipped feature before anyone stops to check whether it was actually agreed. Speed does not create the “I never agreed to that” problem. It removes the delay that used to catch it.
What a decision log actually records
A decision log is not meeting minutes and it is not a status update. Minutes record what was said. A log records what was decided, and just enough around it that the decision can be understood and, if needed, reopened on its merits. For each entry, four things:
- The decision itself, stated as a claim you could disagree with. Not “discussed pricing” but “we ship three tiers, not usage-based billing, for launch.”
- The context that forced it, in a sentence or two. What was true when you decided. This is what lets a future reader judge whether the decision still holds or the ground moved under it.
- The alternatives that lost, named. The point is not thoroughness. It is that “usage-based billing” being visibly considered-and-rejected stops someone reopening it in three weeks as if it were a fresh idea.
- Who owns it, so there is a person to ask, not a committee to reconvene.
That is the whole discipline. Notice what is missing: a long rationale document, a template with fifteen fields, an approval workflow. A decision log that costs more than a couple of minutes per entry does not get kept, and a log that is not kept is worse than none, because now people trust it and it is stale.
Where it has to live
The most common way a decision log dies is location. It goes into a wiki page nobody opens, or a document that is one folder too far from the work, and within a month it is fiction. The rule that keeps a log alive is proximity: the decision has to live where the work that depends on it lives.
A decision about an API contract belongs next to that contract. A decision about what a feature does and pointedly does not do belongs attached to that feature, not in a separate governance space. When the decision is one click from the thing it governs, two things happen. People actually record decisions, because it is not a context switch. And people actually read them, because they are already looking at the surrounding work when the question comes up.
This is the same failure that kills most documentation, and it is worth being blunt about it. A record disconnected from the work it describes rots, because nothing forces it to stay true and nothing puts it in front of the people who would notice it is wrong. A decision log is not exempt. If it is a dead document in a corner, it will drift out of sync with reality exactly like every stale PRD you have ever ignored. The log has to be close enough to the work that keeping it true is cheaper than letting it lie.
Who consults it, and when
A log nobody reads is a diary. The value shows up at four specific moments, and it is worth designing for them:
- When a settled question gets reopened. Someone proposes usage-based billing again. Instead of a fresh debate, you open the entry: here is when we decided against it and why. Now the conversation is the right one, which is “has the context changed?” and not “what did we even decide?”
- When someone joins. A new person does not absorb months of decisions by osmosis or by interrupting everyone. They read the log and inherit the reasoning, not just the outcome.
- When something breaks and you need to know if it was on purpose. Half of “why is it built this way” questions are answered by “we decided that, here’s the tradeoff.” The other half reveal a real mistake. The log tells you which is which, fast.
- When agents build. This is the new one. An agent working from a current decision produces code that matches what the team actually chose. An agent working from a stale or unstated decision confidently builds the thing you rejected. The log is what a decision looks like when it is durable enough for a machine to build against without re-asking a human every time. It is one strand of the product memory a team keeps outside anyone’s head.
The decision log and the feature factory
There is a deeper reason this matters, and it connects to how a team avoids becoming a feature factory. A feature factory ships output and never asks whether the output changed anything, because it has no memory of why each thing was built. Decisions are made, forgotten, and re-made slightly differently, so the product accretes features that no longer share a coherent intent.
A decision log is the thin end of the wedge against that. It forces the team to state what it is choosing and why, which means later you can ask the question a factory never asks: did this decision produce the outcome we bet on? You cannot connect a decision to its result if you never recorded the decision. Keeping the log is the precondition for making product a matter of installed behavior rather than shipped features, because behavior change is something you can only judge against an intent you wrote down.
Where PaellaDoc fits
This is the specific problem I am building PaellaDoc to make structural rather than heroic. A decision should not depend on the strongest memory in the room. When a choice is made, it gets captured as a first-class thing, next to the artifacts and code it governs, with its context and the alternatives it beat. It stays connected to the work, so it does not rot into a document nobody trusts, and the agents build against the decision that actually holds rather than a half-remembered version of it.
The “I never agreed to that” problem never survives contact with a real record. The whole difficulty was that there was nothing to point at. Give the team something to point at, keep it close to the work, and the argument stops being about the past. It goes back to being about the only thing worth arguing over: what to decide next.
Frequently asked questions
What is a product decision log?
A product decision log is a lightweight record of the choices a team makes, captured as they happen. Each entry states the decision as a claim you could disagree with, the context that forced it, the alternatives that lost, and who owns it. It is not meeting minutes, which record what was said. A log records what was decided, close enough to the work that it stays true.
What should I record in a decision log?
Four things per entry, no more. The decision itself, stated as a claim (“we ship three tiers, not usage-based billing, for launch”). The context that forced it, in a sentence or two. The alternatives that lost, named, so nobody reopens them as fresh ideas. And who owns it, so there is a person to ask. Skip the long rationale and the fifteen-field template, or the log stops getting kept.
Where should a decision log live?
Next to the work it governs, not in a wiki page nobody opens. A decision about an API contract belongs beside that contract; a decision about what a feature does and does not do belongs attached to that feature. When the record is one click from the thing it governs, people actually write decisions down and actually read them. Distance is what kills a log.
How is a decision log different from meeting minutes?
Minutes record what was said; a log records what was decided. Minutes are a transcript of a conversation, so they preserve the ambiguity that caused the “I never agreed to that” problem in the first place. A log resolves it into a single claim with its context and rejected alternatives, durable enough that a teammate, a new hire, or an agent can build against it without re-asking.