The decisions survive in the code. The reasoning dies in Slack.

On this page

A developer on r/sysadmin spent their morning searching three years of Slack to figure out why their OIDC flow is the one it is. The engineer who set it up left without writing anything down. The decision is still there. It is configured, deployed, working. The reason is gone.

This is not an unusual story. It is the pattern.

We have spent twenty years preserving the wrong artifact. The code is the output. The reasoning is the input - the constraints, the trade-offs, the option that was almost picked and the reason it was not. We save the output. We lose the input. Then we are surprised when the next person cannot work with the system.

What ADRs got half-right

Architecture Decision Records made the right move. Pull the reasoning out of someone's head and put it in the repo, close to the code it explains.

The half-right part is the time stamp. An ADR captures intent at a moment. The code keeps changing. A year later the ADR describes a decision about a service that has since been split, renamed, or refactored. The doc is technically correct and practically useless.

ADRs assumed the system would slow down enough for documentation discipline to catch up. The opposite happened.

The static prompt is already out of date

A common defense right now is the long system prompt. A block of context pasted into Cursor or Claude Code that tells the agent how this codebase works, what the conventions are, what to avoid.

It works for a week. Maybe a month.

Then the codebase moves. Someone changes the auth pattern. Someone retires a service. Someone splits the order module. The prompt does not move with it. The agent confidently writes code based on rules that are no longer true.

Static context has a half-life. The codebase does not.

This is what sits behind every "AI got me 80% of the way there" complaint you read this month. The missing 20% is reasoning the agent could not see. Not because the model is weak. Because the why was never written down in a place the agent could reach.

What living reasoning looks like

A few things have to be true for architectural reasoning to actually keep up.

It has to live next to the code it explains, not in a separate wiki. Wikis die because no one is forced to walk past them.

It has to be structured, not just prose. You should be able to query it - "what depends on the payments boundary, and why is it shaped that way" - the same way you query the code itself.

It has to update when the code updates. Manually, automatically, or both. The point is that the gap between the artifact and the reasoning never grows wider than a few days.

This is what we are building ProvenMap for. Architectural reasoning that lives where the code lives, evolves when the code evolves, and is reachable by the people and agents who need it - not just the architect who wrote it.

The shift

The framing most teams still use is "we need better documentation." That framing has not produced better outcomes in twenty years and it will not start now.

The shift is to treat reasoning as a first-class artifact. Versioned with the code. Updated with it. Useful to humans and agents alike.

The decisions will keep surviving in the code either way. The question is whether the reasoning survives with them, or dies in Slack.