Decisions that don't rot: keeping decisions up to date

A decision starts rotting the moment you make it. Not in a year, not when someone leaves - immediately. The context that made it correct keeps moving: the load doubles, the vendor changes terms, the library you chose gets deprecated, the constraint you optimized around disappears. The decision sits still while the world it described walks away. Keeping decisions up to date is not a documentation hygiene problem you can solve with more discipline. It is a data problem, and the fix is to treat a decision as a living record with its full history attached, not a sentence frozen in a doc.

Most teams already sense this. They have a Notion page called "Decisions" with eleven entries, the last one from March, and nobody trusts a word of it. The page did not fail because people are lazy. It failed because the format asked a human to remember, by hand, to come back and revise a static line every time reality shifted under it. No one does that. So the log decays, and a decayed log is worse than nothing.

A stale decision log gives false confidence

A blank page is honest. It tells you to go ask someone. A confident, outdated decision record lies to your face.

Here is how it plays out. A new engineer named Priya picks up a ticket to extend the billing retry logic. She finds the decision doc: "We retry failed charges three times over 48 hours, then dunning." Clear, dated, signed off. She builds against it. What the doc does not say is that four months ago, after a wave of chargebacks, the team quietly moved to a single retry plus an immediate email, and the change lived only in a Slack thread and the code. Priya ships something correct according to the record and wrong according to production. The review catches it, maybe. Or it does not, and a customer gets charged twice.

This is the documented failure mode of decision records. The widely cited guidance on architecture decision records is blunt about it: a stale decision log is worse than no log, because it gives false confidence. The recommended practice is that you never edit an accepted decision. When the conclusion changes, you write a new record that supersedes the old one and link them, marking the original "Superseded by" the new one. That convention exists precisely because overwriting destroys the one thing that makes a decision trustworthy later: the trail of why it used to be something else.

The convention is right. The problem is that it is a manual ritual, and manual rituals are the first thing to go when a team is shipping.

The reason is the asset, not the conclusion

Ask what a decision is actually for. Not the conclusion - the conclusion you can usually reverse-engineer from the code. What you cannot reverse-engineer is the reason. Why three retries and not one. What we knew about chargebacks at the time. Which option we rejected and what would have to change for us to reconsider it.

That reasoning is the expensive part, and it is the part conventional logs throw away. They record the verdict and lose the argument. So six months later, when someone proposes "let's just retry five times, more is better," nobody can say "we tried that, here is what broke," because the record is a single declarative line with no memory of the road it took to get there.

A decision you can keep up to date has to carry three things together: the before, the after, and the reason for the move. Drop any one and the record rots faster. Keep the conclusion but lose the reason, and you cannot defend it. Keep the reason but overwrite the before, and you cannot see the trajectory - whether this is the third time the team has flip-flopped on the same call, which is itself the most useful signal in the building.

Why "just write better ADRs" does not scale to a team of 20

Architecture decision records are good. If your team writes them and maintains the lifecycle, you are ahead of most. But the lifecycle is the catch. The whole model assumes a disciplined author who, on every reversal, opens the repo, writes a new markdown file, updates the status field on the old one, and links them. It assumes decisions happen in a place where writing a file is natural.

On an AI-native engineering team, decisions do not happen there. They happen in a Slack thread at 11pm, in a PR review comment, in a Linear ticket, in a standup someone summarized in four words, in a conversation between an engineer and Claude Code. The decision is real and it is made; it is just scattered across six surfaces, none of which is the decision log. Asking a busy team to also transcribe each of those into a formal record, and then to keep coming back and revising them, is asking for a second job nobody signed up for. So they do not, and the log drifts from reality - the exact failure the ADR guidance warns about.

The honest read: keeping decisions up to date by hand does not fail because of bad people. It fails because the place a decision is made and the place it is recorded are different places, and the gap between them is paid in human memory, which is the least reliable storage medium you own.

Keeping decisions up to date where the decision actually lives

The way out is to stop treating a decision as a document and start treating it as a node in a team knowledge graph: a typed record connected to the work it governs and to the signals that can change it.

This is what Ody does with its Decisions module. It captures decisions from the tools where they are actually made - Slack, Linear, GitHub, Google Docs, standups, coding agents - and stores each as a living record that carries a before-to-after diff, the reason, and the date. When new signal contradicts a standing decision - a PR that retries once where the record says three times, a thread that overturns last quarter's call - Ody does not quietly rewrite history. It surfaces the contradiction to the decision's owner and nudges: this looks changed, confirm or revise?

That last part is the whole design. Ody senses continuously and automatically, but it acts only when a human says so. A nudge is the ceiling of its autonomy. There are no silent overwrites, because a decision changed by a machine with no human in the loop is exactly how you get a log that is confidently, invisibly wrong. The point is not to automate decisions away from people. It is to make the act of keeping a decision current cost one click instead of a scheduled writing session that never happens.

When a decision does change, the old version is not deleted. It is kept and linked, the way the ADR convention says to supersede rather than edit - except the chain is maintained for you, so the third flip-flop on the retry policy is visible as a flip-flop, not laundered into a clean-looking line.

A changed decision is a change, not a conflict, and there is a longer argument for why belief revision deserves to be first-class in the case for treating change as a change. This piece is the narrower claim: that a decision is a perishable thing, and the only way to keep it fresh is to give it a memory and let it raise its hand when the ground moves.

What "up to date" should actually feel like

You will know your decisions are current when the new engineer stops asking "is this still true?" - because the record itself tells her. When the doc says "decided three retries, March; revised to one retry plus email, July, after chargeback spike," with both versions linked and the reason on each, Priya does not ship the wrong thing. She reads the trajectory, sees the live conclusion, and sees why the obvious-sounding "just add more retries" was already tried and abandoned.

That is the difference between a decision and a decision log. A log is a graveyard of conclusions. A living decision is a record that knows what it used to be, why it changed, and when something new threatens to make it wrong again.

If you want to see how the before-to-after diff plays out across a real week of a team's work, walk through a week in one team, or book a demo and bring your messiest decision doc.