The Architecture Decision Was Made in a Meeting. It Was Never Written Down.

The auth service calls the billing service directly on every login. Synchronously, inside a transaction. If billing is down, logins fail. The question is: why? Why not an async event? Why couple login availability to billing availability? Why is this transaction boundary where it is? The engineers who made that decision in a design meeting three years ago could have answered in thirty seconds. Today, two of them are at different companies, one doesn't remember the details, and the fourth is on the team but remembers the outcome, not the reasoning.

Architecture Decision Records exist precisely to prevent this. They were supposed to capture the context, the alternatives considered, the constraints that drove the decision, and the expected tradeoffs. The ADR for the auth-billing coupling was supposed to be written the week after the meeting. It never was. The meeting notes weren't saved. The decision became part of the codebase without becoming part of the institutional memory, and three years later nobody can confidently explain it.

Why verbal decisions don't become written ones

Writing documentation after a meeting is a low-urgency task competing with high-urgency implementation work. In the week after the architecture meeting, the decision is fresh in everyone's minds — which makes writing it down feel redundant. "Everyone knows." But the people who know are the ones in the room, and their knowledge fades with time and turnover.

The ADR gets written when there's time for documentation work — which is usually never. Or it gets written retroactively when someone joins the team and asks the question, by which point the people who could have answered it with full confidence have moved on. The ADR written from memory six months later is better than nothing but worse than the one written the week of the decision.

The lifecycle of a verbal architecture decision:

  Day 1: Decision made in design meeting. 5 people present. Context: clear.
  Day 7: ADR was supposed to be written. Not written. Everyone busy.
  Month 1: Engineers on the call remember the decision. Context: fading.
  Month 6: One engineer left. Others have moved to different areas. Context: partial.
  Year 1: New engineer joins team, asks why auth calls billing directly.
    → Engineer A: "I think it was a performance thing?"
    → Engineer B: "No I think it was about consistency guarantees"
    → Engineer A: "Maybe both?"
  Year 2: Decision can no longer be reconstructed.
    → The next engineer who wants to change it has no context.
    → They either leave it (technical debt) or change it and break something.

The cost of undocumented reasoning

When the reasoning behind an architectural decision is lost, the next engineer who touches that area has three options: leave it alone (technical debt compounds), change it without understanding the constraints (risk of breaking things for reasons they don't understand), or spend significant time reconstructing the context through code archaeology, Slack searches, and conversations with people who might remember.

All three options are worse than having the ADR. Leaving things alone is safe but not scalable. Changing without context creates incidents. Reconstruction costs days and produces approximate answers. The ADR that wasn't written saves zero time in the short term and costs enormous time over the life of the system.

What the codebase shows vs. what it doesn't:

  Shows:
  -> auth-service calls billing-service synchronously on login
  -> The call is wrapped in a transaction
  -> Failure causes the login to fail

  Doesn't show:
  -> Why sync instead of async event
  -> Why this transaction boundary
  -> What alternatives were considered and rejected
  -> What the failure mode is supposed to be
  -> Whether this is intentional or an accident that became convention

  The what is in the code. The why is in someone's head, or gone.

What AI can and can't recover

AI codebase tools can surface what was decided — the behavior encoded in the code. The auth-billing coupling is visible and navigable. The transaction boundary is clear. What AI cannot reliably recover is why: the alternatives that were rejected, the constraints that drove the choice, the incident that shaped the approach. The "why" requires the human context that never made it into the artifact.

What Kognita can do is make the "what" fully accessible — the current behavior, the dependencies, the change history, the relevant tests. This doesn't recover the verbal context, but it reduces the surface area of the mystery. The engineer touching the auth-billing coupling knows exactly what it does, how it's been changed, and who to ask about the remaining contextual gaps. That's a better starting point than "ask someone who might remember."

Final take

Verbal architecture decisions become permanent knowledge gaps. The fix is not better recall — it's writing the reasoning down before the meeting context fades. The codebase preserves the outcome. Only documentation preserves the reasoning. And when the reasoning is gone, every engineer who touches the system pays for its absence with investigation time, caution, and occasional well-intentioned breaks.

The codebase shows what was decided. It rarely shows why. Writing down the why is the one form of documentation that cannot be reconstructed from the code — and the one most consistently skipped.