Tribal Knowledge: Get It Out of Heads, Into the Repo
THE REPO DOESN'T KNOW
Tribal knowledge is everything your team knows that the repo doesn't. Why it accumulates, what it costs, and how to move it out of heads on purpose.
TL;DR: Tribal knowledge is every load-bearing fact about your system that lives in heads instead of the repo: the whys, the gotchas, the "ask Priya" routing table. It feels free because conversation is fast; it bills you in interruptions (61% of developers spend 30+ minutes a day hunting for answers) and collects the principal at every resignation. You don't fix it with a wiki sprint. You fix it by capturing answers where they surface and spreading context through work the team already does.
Every team has a routing table that appears on no diagram. Deploy questions go to Sam. Billing questions go to Priya. The reason the retry is exactly 7 seconds goes to Marek, who inherited the answer from someone who left in 2023. The system works - questions get answered, code ships - right up until someone on the routing table gives notice, and a chunk of your operational reality walks out with a cardboard box.
That's tribal knowledge: the part of your system that exists only in people. This article is about what it is, what it quietly costs, where it pools, and how to move it into the repo without a documentation crusade nobody finishes.
What is tribal knowledge?
Tribal knowledge is the unwritten, socially transmitted know-how a team depends on: context that has never been captured anywhere a newcomer - or a search box - could find it. In software teams it takes recognizable forms:
- The whys. Why it's built this way, why the obvious alternative was rejected, why that config value is sacred. Code shows what; only heads hold why.
- The operational folklore. How the deploy really works when the script fails, which alerts are noise, why you never run the backfill on a Friday.
- The routing table. Who actually knows each area: knowledge about where the knowledge is, itself unwritten.
- The landmine map. Which module is load-bearing despite looking dead, which test is flaky, which vendor API lies.
Notice what's not on the list: the code itself. You keep the code when people leave. What you lose is everything that made the code operable and changeable, which is why teams that "have the source" can still find themselves unable to touch it. The knowledge and the codebase are different assets, and only one of them is in version control.
Why teams run on tribal knowledge
Because at any single moment, it's the rational choice. Answering a question in Slack takes two minutes; writing the durable version takes twenty and might never be read. Explaining the deploy to the new person takes one coffee; maintaining a runbook is a chore with no deadline. Every individual trade favors the head over the repo. The sum of those correct local decisions is an org whose operating manual is distributed across skulls.
So nobody is to blame here, and that matters for how you fix it (roast the system, never the person). The expert answering questions all day is subsidizing the missing documentation out of their own focus time. Tribal knowledge is simply the default state of any team that has never made capture cheaper than conversation.
What tribal knowledge costs
Two bills, on different schedules.
The daily interest is paid in interruptions and searching. In the 2024 Stack Overflow Developer Survey, 61% of professional developers reported spending more than 30 minutes a day searching for answers or solutions, 45.2% agreed that knowledge silos prevent them from getting ideas across the organization, and 30% said silos hurt their productivity ten or more times a week. That is tribal knowledge operating normally: the answers exist, but retrieval means finding the right head and interrupting it. Multiply half an hour a day across your payroll and the "free" system stops looking free.
The principal comes due at departure. Knowledge held only in a head has the same failure mode as data with no backup, and the backup-less case is common: Avelino et al. (2016) found 45 of 133 popular GitHub systems (34%) at a truck factor of exactly 1, and roughly 65% at 2 or lower. When the one person who holds an area leaves, the tribal knowledge of their areas doesn't transfer in the exit interview; it evaporates. The full risk picture is the bus factor story, and the human side of it is key-person risk.
Where does tribal knowledge pool?
You can't capture everything, so find where the only-copy risk is concentrated. Two signal sources, no survey required:
- Follow the questions. Which topics always route to the same person? The names that appear in every "quick question" thread are holding the densest tribal knowledge. If your chat tool can show you who gets DM'd about what, your routing table is already written - just not by you.
- Follow the git history. Areas where one name dominates both authorship and review are places where the context has had no reason to leave one head. The mechanics of reading that map are in knowledge silos in engineering teams, and every such area doubles as a bus-factor-1 zone.
Where both signals point at the same area and that area is critical (deploys, money paths, the legacy service in the request path), you've found your capture priorities.
How to get it out of heads and into the repo
Not with a documentation sprint. Wiki crusades produce a burst of pages that are stale in a quarter and unread forever, a shortcut into documentation debt rather than out of it. The durable approach changes the defaults so capture happens where the knowledge surfaces:
- The second-question rule. The first time someone asks, answer. The second time anyone asks the same thing, the answer gets written where the next asker will look - a README, a runbook, a comment at the config value itself - and the reply becomes a link. Demand proves the knowledge is worth capturing; the rule spends effort only on proven demand.
- Capture decisions when they're made. The whys are the most expensive knowledge to lose and the cheapest to record at the moment of decision: a short dated note in the repo with context, options, choice, reasoning. Ten minutes now versus an archaeology project in three years.
- Runbooks next to the code they operate. The deploy steps, the incident checklist, the backfill warnings: short, versioned with the code so they change when the code does, and verified by having a non-expert actually run one.
- Rotate reviewers to spread the unwritten parts. Some context only transfers through working the code. Reviews are the cheapest carrier: Bacchelli and Bird's Microsoft study found the real outcomes of code review lean toward knowledge transfer and team awareness, so a standing second reviewer in each critical area is a tribal-knowledge pump that runs on work you're already doing. The rest of the transfer toolbox (pairing, rotation, and when each is worth its cost) is in knowledge transfer for engineering teams.
Keeping it out of heads
Tribal knowledge regrows at the speed of shipping: every sprint mints new whys, new landmines, new folklore, and conversation will always be the path of least resistance. So treat concentration as a metric, not a project. Watch where single-owner areas are forming and aim the capture rules there while the knowledge is still cheap to move.
That watching is mechanical: a continuously computed ownership map showing which areas' context lives in exactly one head is what Busfactor's knowledge view renders from your existing git history. The repo has been keeping half the evidence all along. The other half is in heads - and heads, unlike repos, don't have a backup schedule. Move the load-bearing parts while it's a workflow tweak, not a crisis.
Frequently asked
What is tribal knowledge in software teams?
Everything your team needs to build and operate the system that exists only in people's heads: why decisions were made, how the deploy really works, which alerts are noise, who to ask about billing. It's transmitted by conversation and lost by departure; nothing in the repo holds it.
Is tribal knowledge always bad?
No. Every effective team runs on some of it, because conversation is the fastest way to move context between two people who are both present. It becomes a liability when it's the only copy: when critical operations depend on knowledge that one resignation, one vacation, or one bad week can take offline.
How do you capture tribal knowledge?
Not with a documentation sprint. Capture it where it surfaces: write down the answer the second time anyone asks the same question, record decision reasoning when the decision is made, put runbooks next to the code they operate, and rotate reviewers so context spreads through daily work instead of ceremonies.
How do you find out where tribal knowledge is concentrated?
Follow the questions and the git history. The areas where every question routes to the same person, and where one name dominates both authorship and review, are where the only copy of the knowledge lives in one head. That's your capture priority list.