Tribal knowledge in engineering teams: measure the bus factor from git history, then convert answers into artifacts

The term covers knowledge that is real, load-bearing, and unwritten. It hides in predictable places: deploy and rollback rituals that only work when a specific person runs them, services nobody touches without asking their historical owner, failure modes known from incidents that predate half the team, and the reasoning behind configuration that looks arbitrary but is not.

The cost shows up as interrupt load and fragility rather than as a line item. Senior engineers lose hours a week to questions they have answered before. Onboarding stretches because the map of the system lives in scheduled calls instead of artifacts. And a single resignation or a two-week vacation can stall a whole subsystem, which is the scenario the bus factor names: the number of people who would have to disappear before nobody can maintain a piece of the system.

You do not need a survey to find the risky areas. Commit authorship per directory is a rough but honest proxy: if one name wrote 85 percent of the commits in services/billing over the last year, billing knowledge is concentrated in one head, whatever the org chart says.

Use a 12-month window so departed engineers and ancient history do not distort the picture, and read the distribution rather than the totals: three authors at 40/35/25 is healthy, one at 90 percent is a risk regardless of volume. The caveats are real, authorship is not understanding, reviewers learn code they never committed, and bulk refactors inflate counts, but as a ranking of where to look first, the proxy holds up. Research backs the concern: a 2016 study by Avelino and colleagues estimated truck factors for 133 popular GitHub projects and found roughly two thirds of them at two or below.

# Commits per author for one directory, last 12 months.
# One dominant name = concentrated knowledge in that area.
git log --since="12 months ago" --no-merges --format='%an' -- services/billing/ \
  | sort | uniq -c | sort -rn | head

# The same sweep across every service directory:
for d in services/*/; do
  echo "== $d"
  git shortlog -sn --no-merges --since="12 months ago" -- "$d" | head -3
done

Most tribal knowledge already gets written down, once per question, in chat, where it sinks beyond retrieval within days. The cheapest conversion habit exploits that: any answer that took more than five minutes to compose gets pasted into the team wiki before the thread closes, and the next occurrence of the question gets a link instead of a rewrite. The marginal cost is about a minute, because the hard part, composing the answer, already happened.

The habit compounds where questions repeat, so track repeats loosely: when you notice yourself answering something for the third time, that is the signal the artifact is overdue. When the recurring question is topological, how does X reach Y, what sits between the API and the warehouse, the right artifact is a diagram rather than a paragraph, and a shared diagram link that unfurls in Slack answers it in one glance.

For a deliberate audit, run a knowledge-mapping session. Draw a grid: systems and critical processes as rows, team members as columns. Each person marks each row honestly with one of three levels: could fix this alone at 2am, could struggle through with the docs, or no idea. It takes 45 minutes for a team of eight and does not require preparation.

Read the columns and the rows separately. A row with a single 2am-capable name is a bus factor of one, and it goes on a risk list with a named remediation: a pairing rotation, a documented walkthrough, or a diagram plus runbook. A column that is 2am-capable on everything belongs to the person whose vacation you should fear, and whose interrupt load you should measure. Rerun the grid twice a year; comparing two snapshots shows whether remediation actually moved anything.

When the concentrated knowledge is system knowledge, what talks to what, where state lives, what breaks first, the fastest conversion is a diagram, for a blunt reason: correcting is faster than authoring. An hour of a senior engineer explaining the billing flow is mostly topology, and topology compresses into a picture that takes minutes to review. Generate a first draft, then let the expert fix it, and you skip the blank-page hour that keeps these artifacts unwritten.

Two generation paths fit here. Describing the system in plain English in Datadef produces an editable draft in one pass. Or an AI agent connected to the Datadef MCP server can draft the map from what it reads in the repository, which grounds the diagram in code rather than in the same tribal memory you are trying to escape. The honest boundary: diagrams capture structure, not reasoning. The why behind decisions still needs written records, and that prose is a human job.

• Keep onboarding docs up to date
• The cost of outdated documentation
• Documentation debt
• Embed diagrams in Slack