Bus Factor
debt(d7/e5/b7/t5)
Closest to 'only careful code review or runtime testing' (d7). The detection_hints specify git-log and github-blame as tools, but automated detection is explicitly marked 'no'. Identifying a bus factor of 1 requires manual inspection of commit history, knowledge audits, and team interviews — it surfaces only through deliberate review, not automated tooling. It rarely becomes visible until someone is actually absent.
Closest to 'touches multiple files / significant refactor in one component' (e5). The quick_fix requires pair programming, documentation, runbook creation, and rotating ownership across critical components. This isn't a one-line fix — it touches multiple systems, people, and processes, but it's not a full architectural rework. It's a sustained effort across several work streams within the team.
Closest to 'strong gravitational pull' (b7). A low bus factor on critical systems shapes every decision about deployment, incident response, and onboarding. Common mistakes show it affects on-call, code review, production debugging, and tribal knowledge — almost every operational concern is coloured by who knows what. It applies broadly across web and cli contexts per applies_to, making it a wide-reach structural liability.
Closest to 'notable trap (a documented gotcha most devs eventually learn)' (t5). The misconception field directly states the trap: developers assume bus factor is only a concern for large teams with specialists, when in fact a two-person team with a bus factor of 1 is equally at risk. This is a well-documented but commonly held wrong belief, making it a notable trap rather than a catastrophic or minor one.
Also Known As
TL;DR
Explanation
The bus factor (also called truck factor or lottery factor) quantifies how much critical knowledge is concentrated in a small number of individuals. A bus factor of 1 means a single person holds unique, undocumented knowledge essential to the project — their departure, illness, or unavailability would severely disrupt development. Mitigations include: pair programming, code reviews that spread knowledge, comprehensive documentation, rotation of ownership, and avoiding single points of expertise. Healthy teams aim for a bus factor greater than 3 on all critical subsystems.
Common Misconception
Why It Matters
Common Mistakes
- Single owners for critical systems with no documentation or knowledge sharing.
- Code that only one person understands because it was never reviewed or pair programmed.
- Tribal knowledge in people's heads rather than in wikis, runbooks, and comments.
- Not rotating on-call responsibilities — only the original author knows how to debug production.
Code Examples
// Bus factor 1: only Alice knows this system:
// - No documentation
// - No code comments
// - No runbook for incidents
// - Alice is the only one with production SSH access
// - Alice goes on holiday → team cannot deploy or debug
// Mitigation: pair programming, docs, access sharing, code reviews# Bus factor = number of people who must be hit by a bus before project fails
# Bus factor of 1 = single point of failure — extremely fragile
# Measuring bus factor:
$ git log --format='%ae' | sort | uniq -c | sort -rn
# If one email owns 70%+ of commits → high risk
# Mitigation strategies:
# 1. Pair programming — knowledge transfers naturally
# 2. Document non-obvious decisions (Architecture Decision Records)
# 3. Rotate ownership: different people merge PRs each week
# 4. Record on-call handoffs — include: current issues, contacts, gotchas
# 5. Runbooks for every operational procedure
# Architecture Decision Record (ADR) format:
# docs/adr/001-use-redis-for-sessions.md
# Title, Status (accepted), Context, Decision, Consequences
# Target bus factor >= 3 for critical systems