Why Does This Code Work? Nobody Knows Anymore.

The retry multiplier is 1.47. Not 1.5, not 2.0 — 1.47. The comment says "empirically determined." The engineer who determined it empirically left two years ago. The load tests that produced that number are gone. The production incidents that shaped it are documented nowhere. The value works. Nobody knows why it works. Nobody touches it.

Every codebase accumulates sections like this. Code that works correctly and cannot be explained. Code where the institutional memory that would justify the specific values, the specific behavior, the specific edge case handling has fully decoupled from the code itself. The knowledge was in someone's head when it was written. It left when they did, or faded when they moved to a different team. What remains is behavior that the team trusts but cannot reason about.

How unexplained code becomes untouchable code

Engineers develop a rational strategy for code they don't understand: leave it alone. If it's working, touching it is pure downside risk. The change might break something in a way that's hard to diagnose, for reasons that aren't obvious, in a production system that has to stay up. The engineering calculus is clear — if it works and you don't understand it, don't change it.

This produces untouchable code: sections of the codebase that all engineers know exist and all engineers avoid. Features that would benefit from changes to the untouchable section get designed to work around it instead. The complexity of the workarounds accumulates. The codebase becomes more contorted with each sprint as new work navigates around the things nobody will change.

Real comments that signal tribal knowledge gaps:

  // empirically determined
  const RETRY_MULTIPLIER = 1.47;

  // do not change without talking to @evan (who left in 2022)
  const BATCH_SIZE = 237;

  // this seems wrong but it works
  const offset = index - 1;

  // legacy logic, don't touch
  function handleSpecialCase() { ... }

  // TODO: understand why this is necessary
  // Added 3 years ago. Comment still here.

Each of these is a place where the team decided
understanding was less safe than leaving it alone.

The confidence problem

Unexplained code creates a specific kind of engineering anxiety: the suspicion that the thing you want to change might be load-bearing in a way you can't see. The retry multiplier of 1.47 might be fine to change to 1.5. Or it might be the value that keeps the system from overwhelming a downstream service under a specific load pattern that only occurs at month-end. Without the context, you can't tell.

This anxiety is rational and appropriate. The appropriate response to it is investigation before change — understanding what the code does, how it's been changed before, what tests cover it, what the change history looks like. All of that is in the codebase and is navigable with good tooling. What can't be recovered from the codebase is the specific reasoning behind the specific values — that's the irreplaceable part of the tribal knowledge.

What codebase AI can surface about mysterious code

For code that nobody understands, AI codebase tools surface the context that does exist: what the code does, where it's called, what tests cover it, what it's changed in its history, what PR descriptions have described. This doesn't explain the 1.47 — but it tells you how often this value has been touched, whether there are tests that would catch a change, and whether any recent changes suggest the original constraints are still in play.

Kognita makes this navigable for any engineer — not just the ones with the intuition to run the right git commands. A new engineer who asks "why is the retry multiplier 1.47?" gets the full history of changes to that value, the test coverage around it, and the related configuration in context. It's not the answer Alice would have given. But it's a much better starting point than "the comment says empirically determined, don't touch it."

What accumulates around code nobody understands:
  -> Workarounds instead of fixes ("route around it, don't touch it")
  -> Increasingly complex code to avoid the mysterious core
  -> New features built outside the affected service
  -> Incident runbooks that say "restart if it behaves oddly"
  -> Onboarding docs that say "avoid this module"
  -> Team members who stop suggesting improvements to that area

  The code works. The system around it becomes contorted.

Final take

Code that works but can't be explained is a form of technical debt that compounds differently from the usual kind. It doesn't slow you down today — it creates permanent conservatism around a section of the system, and that conservatism shapes every future architectural decision. The fix is not to touch it recklessly. It's to build enough understanding to touch it confidently — which requires the codebase history, not the tribal memory that's already gone.

The comment says "empirically determined." The engineer who determined it is gone. The codebase still has the commit history, the tests, and the change context. Start there before you decide whether 1.47 can become 1.5.