What Is Tribal Knowledge in Software?

Every long-lived system carries a second system inside it — one that runs alongside the code but isn’t written anywhere. It is the set of rules people know: that this customer is invoiced differently, that this batch must run before that one, that the field is validated the way it is because of an incident years ago. The code enforces those rules. The people explain them. That second, unwritten system is tribal knowledge, and it is usually the most valuable and least protected asset a legacy system has.

A working definition

Tribal knowledge is the understanding a system depends on that exists only in people’s heads. Not in the code comments, not in the wiki, not in the runbook — in the memory of whoever has worked on it longest.

It is “tribal” because it travels by membership, not by record. You learn it by being on the team long enough to absorb it: a hallway answer, a “oh, don’t touch that, here’s why,” a debugging session where someone explains the thing that was never going to be obvious. New members are inducted into it gradually. People who leave take their share with them.

The defining trait is that it is invisible until it’s gone. While the people who hold it are present, the system appears fully understood — every question has an answer, every incident gets resolved, every change ships. Nothing signals that the understanding lives in three heads rather than in the repository. The gap only becomes visible at the worst possible moment: when someone is asked to change a part of the system that only a departed colleague truly understood.

Why it accumulates — and why that’s rational

It is tempting to read tribal knowledge as a documentation failure, a sign of a sloppy team. It usually isn’t. It is the predictable result of a stable one.

When the people who built a system are still maintaining it, writing the knowledge down has almost no payoff. The knowledge in their heads is faster to use than any document could be; the document would only ever serve a future stranger who, right now, doesn’t exist. So the rational engineer spends the hour fixing the bug, not documenting the rule behind it. Multiply that decision across a decade and thousands of small rules, and you get a system whose real behavior is enormously well understood by a handful of people and recorded almost nowhere.

That is why tribal knowledge correlates with the systems you’d least want to lose. The longer a system has run and the more business it has absorbed, the denser its tribal knowledge — and the smaller, usually, the group that still holds it.

What it actually looks like

In practice, tribal knowledge clusters around the parts of a system that the original specification never captured:

• Business rules with no document. The discount that applies to one account, the tax edge case, the rounding convention that has to match a downstream partner’s to the cent.
• Ordering and timing. The job that must finish before another starts; the reason a process runs at 2 a.m. and not 4.
• The handling of bad input. A malformed record that some downstream step has quietly depended on being handled a particular way for fifteen years.
• The reasons-why. Not what the code does — you can read that — but why it does it. The incident, the regulator, the one big customer behind a branch that otherwise makes no sense.

The first three are recoverable from the code with enough effort. The fourth — the why — is the part that lives almost exclusively in people, and the part whose loss hurts most, because without it the next engineer can’t tell a load-bearing rule from an accident and is afraid to touch either.

Why it’s a modernization problem specifically

For a stable system with a stable team, tribal knowledge is a manageable risk. It becomes acute under two conditions, and modernization sits at the intersection of both.

The first is people leaving. The pipeline of engineers fluent in older stacks is thin, and the people who remember why a system behaves as it does are, on average, the closest to retirement. IBM figures, reported via Fujitsu in 2020, put the average COBOL developer’s age at roughly 58, with about 10% of that workforce retiring each year. Every departure takes a share of the unwritten system with it, and that share does not transfer on the way out — it evaporates.

The second is change. Tribal knowledge is dormant as long as no one disturbs the system. Modernization disturbs everything. Rebuild a component from what the team thinks it did, and the gap between that and what it actually did surfaces as a stream of production bugs after cutover — each one a piece of business logic that was silently dropped. This is one of the most reliable ways modernization programs fail, and it compounds with the talent problem: the people who could have caught the gap are often gone before the rebuild starts.

Tribal knowledge isn’t a hygiene issue you fix when there’s time. It’s the single biggest source of hidden risk in changing a system you depend on.

Not everything in those heads is worth keeping

Not all tribal knowledge is worth preserving, and pretending otherwise leads to the wrong instinct. Some of what’s in those heads is genuine institutional value — the rules the business actually runs on. Some of it is workaround for problems you intend to fix, scar tissue around bugs that shouldn’t survive the modernization. The goal is not to canonize everything anyone remembers. It is to surface it all, then decide deliberately what to replicate and what to leave behind — the distinction this series and our parity validation practice keep coming back to. Capturing tribal knowledge is the prerequisite for that choice. You cannot decide to keep or drop a rule you never knew existed.

Where this leads

This part named the knowledge that was never written down. The next part is about the knowledge that was written down — and quietly stopped being true. Part 2, Documentation Drift Explained, covers the other half of why teams don’t actually know what their own systems do: documentation that decays not by disappearing but by diverging, until the diagram on the wall describes a system that no longer exists. Together, the two parts define the problem the rest of the series solves.