| name | forensic-onboarding-risk |
| description | Use when developer is leaving or new hire onboarding, assessing team resilience, planning for developer departures, calculating bus/truck factor, identifying knowledge silos, or evaluating organizational risk - identifies knowledge gaps and transition risks |
Forensic Onboarding Risk Analysis
🎯 When You Use This Skill
State explicitly: "Using forensic-onboarding-risk pattern"
Then follow these steps:
- Identify single-owner files (files with 1-2 contributors)
- Calculate bus factor (minimum people whose loss cripples project)
- Estimate transition risk (productivity loss if key person leaves)
- Cite research when presenting findings (single-owner = 3-5x risk)
- Suggest integration with knowledge-mapping and refactoring-roi at end
Overview
Onboarding risk analysis identifies knowledge gaps when team members join or leave. Research shows single-owner files have 3-5x higher risk of quality issues and delays.
This analysis reveals:
- Bus factor - How many people must leave to cripple the project
- Single-owner files - Code only one person understands
- Knowledge silos - Critical expertise held by one person
- Transition cost - Productivity lost during onboarding/offboarding
- Mitigation priorities - Which knowledge gaps to address first
Core principle: Knowledge should be shared. Single points of failure in knowledge create organizational risk.
When to Use
- Developer is leaving (offboarding risk assessment)
- New hire starting (onboarding plan)
- Team reorganization planning
- Quarterly knowledge health checks
- After key contributor departure (damage assessment)
- Before major project (identify knowledge dependencies)
- Evaluating organizational resilience
When NOT to Use
- Insufficient git history (<6 months unreliable)
- Small team (<3 people, everyone knows everything)
- Greenfield project (no knowledge silos yet)
- When you need code complexity (use complexity analysis)
- When you need coordination overhead (use coordination analysis)
Core Pattern
⚡ THE BUS FACTOR FORMULA (USE THIS)
This is the knowledge risk metric - don't create custom calculations:
Bus Factor = Minimum people whose departure cripples project
Single-Owner Risk = Files where 1 person = >80% of commits
Knowledge Silo Threshold:
- >80% owned by 1 person: CRITICAL (knowledge silo)
- >60% owned by 1-2 people: HIGH (at-risk)
- >40% owned by 2-3 people: MODERATE (manageable)
- <40% distributed: GOOD (shared knowledge)
Transition Cost = Ramp-up Time + Lost Productivity + Mentoring Time
Example: 3 months ramp-up + 30% reduced productivity + 20% mentor time
Critical: Bus factor of 1-2 = organizational risk. Project could halt if they leave.
📊 Research Benchmarks (CITE THESE)
Always reference research when presenting knowledge risk findings:
| Finding | Impact | Source | When to Cite |
|---|
| Single-owner files | 3-5x higher defect risk | Microsoft Research | "Single-owner files have 3-5x higher defect risk (Microsoft)" |
| Knowledge silos | 40-60% longer feature delivery | Conway's Law Studies | "Knowledge silos slow delivery by 40-60% (Conway)" |
| Onboarding time | 3-6 months to full productivity | Software Engineering Research | "Average onboarding: 3-6 months to full productivity" |
Always cite the source when justifying knowledge sharing investment.
Quick Reference
Essential Git Commands
| Purpose | Command |
|---|
| Contributors per file | git log --since="12 months ago" --format="%an" -- FILE | sort -u | wc -l |
| Primary owner | git log --since="12 months ago" --format="%an" -- FILE | sort | uniq -c | sort -rn | head -1 |
| Single-owner files | Loop through files, count contributors = 1 |
| Contribution % | Count commits per person / total commits × 100 |
Knowledge Risk Classification
| Ownership % | Contributors | Risk | Action |
|---|
| >80% | 1 person | CRITICAL | Immediate knowledge sharing |
| >60% | 1-2 people | HIGH | Schedule pairing/docs |
| >40% | 2-3 people | MODERATE | Monitor, encourage sharing |
| <40% | 3+ people | GOOD | Maintain practices |
Bus Factor Interpretation
| Bus Factor | Risk Level | Meaning | Action |
|---|
| 1 | CRITICAL | One person holds keys | Urgent mitigation |
| 2 | HIGH | Two people critical | Knowledge sharing needed |
| 3-4 | MODERATE | Small core team | Expand expertise |
| 5+ | GOOD | Distributed knowledge | Maintain standards |
Implementation
Step 1: Calculate Ownership Per File
For each file in codebase:
def calculate_ownership(file, since="12 months ago"):
commits = git_log(file=file, since=since)
contributor_counts = defaultdict(int)
for commit in commits:
contributor_counts[commit.author] += 1
total_commits = len(commits)
if total_commits == 0:
return None
ownership = {}
for contributor, count in contributor_counts.items():
ownership_pct = (count / total_commits) * 100
ownership[contributor] = ownership_pct
primary_owner = max(ownership, key=ownership.get)
primary_pct = ownership[primary_owner]
return {
'file': file,
'total_commits': total_commits,
'primary_owner': primary_owner,
'primary_pct': primary_pct,
'all_ownership': ownership,
'contributor_count': len(ownership)
}
Step 2: Identify Knowledge Silos
Find single-owner critical files:
def find_knowledge_silos(ownership_data, criticality_scores):
silos = []
for file_data in ownership_data:
primary_pct = file_data['primary_pct']
contributor_count = file_data['contributor_count']
is_critical = criticality_scores.get(file_data['file'], False)
is_silo = (
(primary_pct > 80 and contributor_count == 1) or
(primary_pct > 60 and contributor_count <= 2)
)
if is_silo:
severity = 'CRITICAL' if (is_critical and primary_pct > 80) else 'HIGH'
silos.append({
'file': file_data['file'],
'owner': file_data['primary_owner'],
'ownership_pct': primary_pct,
'contributors': contributor_count,
'is_critical': is_critical,
'severity': severity
})
return sorted(silos, key=lambda x: x['ownership_pct'], reverse=True)
Criticality score: From hotspot analysis or manual business criticality rating.
Step 3: Calculate Bus Factor
Minimum people whose loss cripples project:
def calculate_bus_factor(ownership_data):
owner_files = defaultdict(list)
for file_data in ownership_data:
if file_data['primary_pct'] > 50:
owner = file_data['primary_owner']
owner_files[owner].append(file_data['file'])
owners_sorted = sorted(owner_files.items(),
key=lambda x: len(x[1]),
reverse=True)
total_files = len(ownership_data)
files_covered = set()
bus_factor = 0
for owner, files in owners_sorted:
files_covered.update(files)
bus_factor += 1
coverage = (len(files_covered) / total_files) * 100
if coverage > 80:
break
return {
'bus_factor': bus_factor,
'coverage': coverage,
'key_people': [owner for owner, _ in owners_sorted[:bus_factor]],
'risk_level': 'CRITICAL' if bus_factor <= 2 else 'HIGH' if bus_factor <= 4 else 'MODERATE'
}
Step 4: Estimate Transition Cost
If person X leaves:
def estimate_transition_cost(person, ownership_data, team_size, avg_salary=150000):
owned_files = [f for f in ownership_data
if f['primary_owner'] == person and f['primary_pct'] > 50]
orphaned_count = len([f for f in owned_files if f['contributor_count'] == 1])
if orphaned_count > 20:
ramp_up_months = 6
elif orphaned_count > 10:
ramp_up_months = 4
elif orphaned_count > 5:
ramp_up_months = 3
else:
ramp_up_months = 2
monthly_cost = avg_salary / 12
ramp_up_cost = monthly_cost * ramp_up_months * 0.5
mentoring_cost = monthly_cost * ramp_up_months * 0.2
total_cost = ramp_up_cost + mentoring_cost
return {
'person': person,
'owned_files': len(owned_files),
'orphaned_files': orphaned_count,
'ramp_up_months': ramp_up_months,
'total_cost': total_cost,
'risk_level': 'CRITICAL' if orphaned_count > 10 else 'HIGH' if orphaned_count > 5 else 'MODERATE'
}
Output Format
1. Executive Summary
Onboarding Risk Assessment (forensic-onboarding-risk pattern)
Bus Factor: 2 (CRITICAL)
Key People: Alice, Bob
Single-Owner Files: 47 (15% of codebase)
Knowledge Silos: 12 critical files
Research shows single-owner files have 3-5x higher defect risk (Microsoft).
DEPARTURE RISK:
If Alice leaves:
- 23 orphaned files (no other contributor)
- 6 critical systems affected
- Estimated transition cost: $75,000
- Ramp-up time: 4-6 months
If Bob leaves:
- 18 orphaned files
- 4 critical systems affected
- Estimated transition cost: $60,000
- Ramp-up time: 3-4 months
RECOMMENDATION: URGENT knowledge sharing needed
2. Knowledge Silos (Single-Owner Files)
Critical Knowledge Silos:
Rank | File | Owner | Ownership | Contributors | Criticality
-----|----------------------------|--------|-----------|--------------|-------------
1 | payments/stripe.js | Alice | 100% | 1 | 🚨 CRITICAL
2 | auth/oauth-provider.js | Alice | 95% | 1 | 🚨 CRITICAL
3 | core/legacy-migration.js | Bob | 92% | 1 | ❌ HIGH
4 | api/webhooks-handler.js | Alice | 88% | 1 | ❌ HIGH
5 | integrations/salesforce.js | Bob | 85% | 1 | ❌ HIGH
Research: Single-owner files have 3-5x higher defect risk (Microsoft).
IMPACT:
- 47 single-owner files total (15% of codebase)
- 12 are business-critical
- If Alice leaves: 23 orphaned (49% of single-owner files)
- If Bob leaves: 18 orphaned (38% of single-owner files)
3. Bus Factor Analysis
BUS FACTOR: 2 (CRITICAL)
Meaning: Project would be severely compromised if these 2 people left
Key People:
1. Alice: Primary owner of 23 files (12% of codebase)
- Domains: Payments, Authentication, Integrations
- Critical files: 8
- Unique expertise: Stripe integration, OAuth
2. Bob: Primary owner of 18 files (9% of codebase)
- Domains: Legacy systems, Core APIs, Database
- Critical files: 6
- Unique expertise: Legacy migration, Database optimization
Coverage Analysis:
- Top 2 people: 80% of codebase knowledge
- Top 5 people: 100% of codebase knowledge
- Team size: 12 developers
RISK LEVEL: CRITICAL
- Bus factor of 2 for 12-person team = severe organizational risk
- Research: Knowledge silos slow delivery by 40-60% (Conway)
RECOMMENDATION: Immediate action required
- Pair Alice/Bob with 2-3 developers each
- Document critical knowledge
- Cross-train on key systems
4. Transition Cost Estimation
DEPARTURE SCENARIO: Alice Leaves
Immediate Impact:
- 23 orphaned files (no other contributor)
- 8 critical systems without expert
- Domains affected: Payments, Authentication, Integrations
Knowledge Gap:
- Stripe API integration (payments/stripe.js)
- OAuth provider setup (auth/oauth-provider.js)
- Salesforce integration (integrations/salesforce.js)
- Webhook processing (api/webhooks-handler.js)
Ramp-Up Estimate:
- Learning curve: 4-6 months to full productivity
- Reduced productivity: 50% for first 3 months, 75% for next 3 months
- Mentoring overhead: 20% of senior developer time
Financial Impact:
- Lost productivity: $37,500 (6 months × $150K × 50% average)
- Mentoring cost: $22,500 (6 months × $150K × 20%)
- Mistake/rework: $15,000 (estimated bugs during learning)
- Total transition cost: $75,000
Timeline Impact:
- Features requiring payment changes: Delayed 3-6 months
- Authentication upgrades: Blocked until knowledge transfer
- Integration work: High-risk period
MITIGATION (Before Departure):
1. URGENT: Pair programming on critical files (2-3 months)
2. Document Stripe integration patterns (2 weeks)
3. Cross-train 2 developers on payments (1 month)
4. Code review all Alice's PRs with knowledge transfer focus
MITIGATION (After Departure):
1. Hire specialist with Stripe experience ($20K+ higher salary)
2. Consulting budget for Stripe integration ($30K)
3. Extended timeline for payment features (3-6 month delay)
Common Mistakes
Mistake 1: Only tracking code ownership, not business criticality
Problem: Flagging single-owner files without considering business impact.
flag all files with 1 contributor
flag single-owner files where (
ownership > 80% AND
(is_business_critical OR is_hotspot OR is_complex)
)
Fix: Always consider business criticality - single-owner test file < single-owner payment file.
Mistake 2: Not estimating transition cost
Problem: Identifying bus factor without quantifying business impact.
Fix: Calculate:
- Ramp-up time (3-6 months typical)
- Lost productivity during transition (50% for 3 months)
- Mentoring overhead (20% of senior time)
- Always translate to dollars for executive decision-making
Mistake 3: Not creating mitigation plan
Problem: Reporting risk without actionable recommendations.
Fix: For each knowledge silo, recommend:
- Immediate: Pair programming (2-3 months)
- Short-term: Documentation (2-4 weeks)
- Medium-term: Cross-training (1-2 months)
- Include timeline and cost for each mitigation
Mistake 4: Not differentiating planned vs emergency departure
Problem: Same mitigation for planned retirement vs sudden departure.
Fix: Two scenarios:
- Planned departure (3+ months notice): Knowledge transfer plan, gradual handoff
- Emergency departure (immediate): Damage assessment, priority triage, external help
⚡ After Running Onboarding Risk Analysis (DO THIS)
Immediately suggest these next steps to the user:
-
Cross-check with code hotspots (use forensic-hotspot-finder)
- Single-owner hotspots = highest risk (knowledge + complexity)
- Prioritize knowledge sharing for these files first
- Refactor to reduce both complexity AND knowledge concentration
-
Check coordination patterns (use forensic-coordination-analysis)
- Single-owner files shouldn't need cross-team coordination
- If they do, create process/documentation
- Reduce coordination dependencies
-
Calculate knowledge sharing ROI (use forensic-refactoring-roi)
- Transition cost = current risk cost
- Knowledge sharing investment = pairing + documentation time
- ROI typically very high (single point of failure expensive)
-
Track bus factor quarterly
- Re-run analysis every 3 months
- Monitor: improving, stable, or deteriorating?
- Validate mitigation efforts are working
Example: Complete Onboarding Risk Workflow
"Using forensic-onboarding-risk pattern, I analyzed knowledge distribution.
BUS FACTOR: 2 (CRITICAL for 12-person team)
Key People: Alice (23 files, 12%), Bob (18 files, 9%)
SINGLE-OWNER RISK:
- 47 files with 1 contributor (15% of codebase)
- 12 are business-critical
- Research: 3-5x higher defect risk (Microsoft)
DEPARTURE SCENARIO: If Alice leaves:
- 23 orphaned files (payments, auth, integrations)
- Transition cost: $75,000
- Timeline impact: 3-6 month delays on payment features
- Ramp-up: 4-6 months to full productivity
MITIGATION PLAN:
1. URGENT: Pair Alice with 2 developers on payments (3 months)
2. Document Stripe integration (2 weeks)
3. Cross-train on OAuth (1 month)
4. Code reviews with knowledge transfer focus
NEXT STEPS:
1. Check hotspots (forensic-hotspot-finder) - Single-owner hotspots?
2. Check coordination (forensic-coordination-analysis) - Process needed?
3. Calculate ROI (forensic-refactoring-roi) - Cost of mitigation?
4. Track quarterly - Measure improvement
Would you like me to proceed with hotspot correlation?"
Always provide this integration guidance - knowledge risk is organizational risk, requires executive attention.
Advanced Patterns
Planned Succession Analysis
Gradual knowledge transfer:
Succession Plan: Alice (Retiring in 6 months)
Phase 1 (Months 1-2): Shadow & Document
- Pair programming on payments (Alice + Junior Dev)
- Document Stripe integration (Alice writes, Junior reviews)
- Expected: Junior reaches 30% proficiency
Phase 2 (Months 3-4): Reverse Shadow
- Junior leads, Alice reviews
- Knowledge validation (can Junior explain to others?)
- Expected: Junior reaches 60% proficiency
Phase 3 (Months 5-6): Independent with Support
- Junior owns features, Alice available for questions
- Handoff critical contacts (Stripe support, etc.)
- Expected: Junior reaches 80% proficiency
Residual Risk: 20% knowledge gap (tribal knowledge)
Mitigation: Alice available as consultant for 3 months post-departure
New Hire Onboarding Plan
Accelerated ramp-up:
New Hire Onboarding (Target: 3 months to productivity)
Week 1-2: Codebase Overview
- Architecture walkthrough
- Local setup, test suite
- Read top 10 most-changed files
- Expected: Can navigate codebase
Week 3-4: First Contribution
- Bug fixes in low-risk areas
- Pair with senior on feature
- Expected: First PR merged
Month 2: Domain Learning
- Payments module deep-dive (pair with Alice)
- Auth system understanding (pair with Bob)
- Expected: Can work semi-independently
Month 3: Full Productivity
- Own small feature end-to-end
- Participate in on-call rotation
- Expected: 70-80% productivity
Critical Knowledge Documentation
Prioritize documentation efforts:
Documentation Priority (High-Impact, Low-Coverage):
1. payments/stripe.js (Alice's, CRITICAL)
- Stripe API integration patterns
- Webhook handling
- Estimated doc time: 2 days
- Impact: Reduces transition risk 60%
2. auth/oauth-provider.js (Alice's, CRITICAL)
- OAuth flow diagrams
- Token management
- Estimated doc time: 1.5 days
- Impact: Reduces transition risk 50%
Total documentation effort: 1 week
Total risk reduction: 55% average
ROI: Very high (1 week prevents $75K transition cost)
Research Background
Key studies:
-
Microsoft Research (2013): Code ownership and quality
- Single-owner files have 3-5x higher defect rates
- Shared ownership improves quality
- Recommendation: Encourage code reviews and pairing
-
Conway's Law Studies (2015): Knowledge silos and velocity
- Knowledge silos slow feature delivery by 40-60%
- Cross-functional knowledge accelerates delivery
- Recommendation: Rotate developers across domains
-
Software Engineering Research (2018): Onboarding time
- Average time to full productivity: 3-6 months
- With good documentation/mentoring: 2-3 months
- Recommendation: Invest in onboarding infrastructure
-
Organizational Risk Research (2016): Bus factor analysis
- Most projects have bus factor of 2-3 (critical risk)
- Bus factor correlates with project abandonment
- Recommendation: Track bus factor as health metric
Why knowledge risk matters: People leave. Knowledge must outlive individual contributors. Bus factor measures organizational resilience.
Integration with Other Techniques
Combine onboarding risk with:
- forensic-knowledge-mapping: Ownership patterns across codebase
- forensic-hotspot-finder: Single-owner hotspots = critical priority
- forensic-coordination-analysis: Single-owner + multi-team = process gap
- forensic-refactoring-roi: Knowledge sharing has quantifiable ROI
Why: Knowledge risk is organizational risk - affects hiring, retention, and business continuity planning.
