Why did we build it this way?

Someone in the planning session proposes moving the retry queue onto the shared worker pool. It is a good idea. It is also the fourth time it has been proposed in two years, and somewhere in the room a person who has been here longer says the sentence that ends the discussion without resolving it: we tried that.

Then the room asks the obvious follow-up. Why did it not work? And nobody can say. The person who ran the experiment has changed teams. The ticket is closed with the word "reverted". So the meeting ends in one of the two bad ways: you spend a sprint finding out again, or you defer to whoever sounded most certain.

The reason is the part nobody writes down

Your team already records a great deal. Tickets record what was done. Commits record what changed. Documents record the state the system ended up in. What none of them record is the reasoning, because reasoning happens out loud, in the ten minutes of argument before someone says "fine, ninety seconds then" and the room moves on.

So the written record keeps the winner and loses the alternatives. That is exactly backwards from what a future reader needs. Nobody re-proposes the thing you chose. They re-propose the thing you rejected, and what they need from you is the reason it lost and whether that reason still holds.

The cost compounds quietly. Constants nobody will touch. Code kept alive by superstition. A quarterly debate that never converges because each round starts from scratch. And the newest person on the team, who is the one most likely to ask the question, is the one least equipped to find the answer.

Three questions, not one

"Why did we build it this way" is really three questions wearing one coat, and separating them is most of the work. Asked one at a time, each has an answer somewhere in the record.

• What did we actually decide, and when? Not what the code does now — what the room agreed to at the time.
• What did we reject, and what rejected it? The constraint that killed the alternative is the load-bearing part.
• What has changed since? Constraints expire. Most re-proposals are correct now and were wrong then.

That third question is the one that makes archaeology worth doing at all. If the answer were always "we decided this and it still stands", the record would only ever settle arguments. In practice it more often reopens them, on purpose, with evidence.

It is also worth noticing who asks. The person most likely to say "why is this like this" is the one who joined most recently, and they are the least equipped to find out, because the answer lives in a conversation they were not in. A team that can answer why gets useful work out of new joiners sooner, and stops paying for the same experiment twice.

A worked example: the ninety-second retry

Take the retry interval. It has been ninety seconds for two years, nobody knows why, and every few months someone proposes lowering it. In Ask Ona, the question to ask is not "why ninety seconds" — it is narrower than that: what did we decide about retry timing on the partner integration, and when.

The answer comes back citing an integration review from eighteen months ago. Someone from the partner's side was on the call and said their rate limit was applied per rolling minute, so anything retried inside that window was refused and counted against the quota twice. Ninety seconds was not an engineering preference. It was their limit plus a margin.

Open that citation and you read the sentence where it was said, which matters, because summaries round things off and this is a detail that a rounded summary would drop. Then ask the third question: has anything about the partner's rate limit changed? A second citation, from a call four months ago, has the same partner mentioning a new tier with a per-hour quota instead.

That is two questions and one citation opened, and the outcome is not "leave it alone". It is that the reason for ninety seconds expired in May and nobody joined the two conversations up, because they were four months and one team reshuffle apart. That is the shape of a good answer to why: not a defence of the past, but a dated reason you can hold against the present.

Making the next decision answerable

Archaeology only works on ground where something was buried. The other half of this playbook is what you say in the room today so that next year's question has an answer. It costs about ninety seconds per decision, and Meeting Notes does the rest: transcript, a summary sized to the meeting, and the decisions pulled out with owners against them.

None of this is a new process, and that matters. Teams abandon decision records because writing one is a separate task that competes with the work. Saying a sentence in a meeting you were already in competes with nothing.

There is one more sentence worth the breath, and it is the one that gets skipped most: when you overturn something, say what you are overturning. "This replaces what we agreed in the March review" costs three seconds and it stops the record from holding two live decisions that contradict each other. Without it, the archaeology works perfectly and returns the wrong answer, which is a worse outcome than returning nothing.

Knowing when to stop digging

Archaeology is not free, and not every why deserves it. The rule of thumb that works: dig when the decision is expensive to reverse, when being wrong is costly, or when the same argument has already come back more than once. Otherwise, redo the thinking. A decision that takes an hour to make again is cheaper to make again than to excavate.

The same judgement applies to how much you say in the room. A team that narrates its reasoning for every choice will produce meetings nobody wants to attend. Reserve it for the decisions that constrain other people's work later, which in practice is a handful per quarter. The Ona for technical and product teams page covers where the rest of a sprint's conversations end up.

Where the trail goes cold

Ona holds what was said in conversations someone recorded. A decision made in a document comment thread, a direct message or a pull request review is not in there, and a good deal of technical decision-making happens in exactly those places. Treat the record as one source among several rather than the source.

It also holds what was said, not whether it was true. If someone confidently misremembered the partner's rate limit on that call, the record preserves the mistake precisely, with a date on it and a citation to make it look authoritative. What the record gives you is a claim and its author. Checking the claim is still a thing a person does.

And it does not read your systems. It can tell you what the team believed the retry interval was; it cannot tell you what it is now, whether anyone changed it quietly, or what the partner's limits currently are. Decision archaeology tells you what the reason was. Confirming that the reason still describes reality is the second half of the job and it belongs to you.

The last one is the plainest. The record reaches back as far as you have been recording and no further. Anything decided before that is still recoverable only by asking the people who were there, which is a fine thing to do — as long as you record that conversation too.