Imported from majiayu000/claude-skill-registry-data (data/forensic-debt-quantification/SKILL.md). Install upstream with npx skills add majiayu000/claude-skill-registry-data --skill forensic-debt-quantification. Copyright stays with the author.

Forensic Debt Quantification

🎯 When You Use This Skill

State explicitly: "Using forensic-debt-quantification formulas"

Then follow these steps:

1. Apply the research-backed cost formulas (see below)
2. Cite specific multipliers (2-3x, 4-9x from Microsoft/Google research)
3. Use conservative estimates and provide ranges (not false precision)
4. Translate to business language (avoid jargon like "cyclomatic complexity")
5. Calculate ROI for proposed refactoring investments
6. Provide opportunity cost (features not built due to debt)

Overview

Technical debt quantification translates code metrics into business language. Instead of "high cyclomatic complexity," explain "this costs us $120K/year in wasted developer time." This skill provides research-backed formulas for calculating the business impact of technical debt.

Core principle: Technical debt has measurable costs - productivity loss, defect risk, coordination overhead, and opportunity cost. Quantify these to make informed investment decisions.

When to Use

• Justifying technical debt work to non-technical stakeholders
• Budget planning for quality initiatives
• Executive reporting on code health
• Prioritizing engineering investments
• Calculating ROI for refactoring proposals
• Quarterly engineering reviews
• M&A due diligence technical assessments

When NOT to Use

• When stakeholders already understand and support quality work
• For greenfield projects without debt accumulation yet
• When precise dollar amounts would be misleading (high uncertainty)
• As the only factor in prioritization (combine with other analyses)

Core Pattern

⚡ THE DEBT COST FORMULA (USE THIS)

This is the research-backed approach - always use these specific formulas:

Total Annual Debt Cost =
  Productivity Loss Cost +
  Defect Risk Cost +
  Coordination Overhead Cost +
  Opportunity Cost

Where all costs are in business terms: dollars, time, or features not built.

Critical: Use conservative estimates (ranges, not exact numbers). Better to under-promise than lose credibility.

📊 Research-Backed Multipliers (CITE THESE)

Always reference the research when using these multipliers:

Always cite the source when presenting these numbers to stakeholders. This builds credibility.

Quick Reference

Essential Formulas

1. Productivity Loss

Productivity Loss = Σ (hotspot_changes × baseline_time × time_tax)

Time tax by complexity:
- Simple code: 1.0x (baseline)
- Moderate complexity: 1.5x
- High complexity: 2.5x
- Critical hotspot: 4.0x

Example:
auth.js: 8 changes/month × 2 hours × (2.5 - 1.0) = 24 hours/month wasted

2. Defect Risk Cost

Defect Risk Cost = hotspot_count × defect_multiplier × avg_defect_cost

Example:
- 10 critical hotspots
- 3x higher defect rate
- $5,000 average defect cost (incident response + customer impact)
- Annual risk: 10 × 3 × $5,000 = $150,000

3. Coordination Overhead

Coordination Cost = high_coord_files × coordination_hours × hourly_rate

High coordination = >7 active contributors

Example:
config.js: 14 contributors, 6 changes/month
Coordination time: 2 hours per change (meetings, conflicts, reviews)
Monthly cost: 6 × 2 × $100 = $1,200/month = $14,400/year

4. Opportunity Cost

Opportunity Cost = (debt_time / total_capacity) × estimated_feature_value

Example:
- 1,800 hours/year on debt-related work
- 10,000 hours/year total capacity (5 devs)
- Debt ratio: 18%
- Could deliver 3-4 more features/year if debt reduced

Cost Inputs (ask stakeholders)

Implementation

Basic Debt Quantification

#!/bin/bash
# Calculate technical debt cost for a codebase

# Inputs (customize these)
HOURLY_RATE=100
TEAM_SIZE=5
DEFECT_COST=5000
TIME_PERIOD="12 months ago"

echo "TECHNICAL DEBT COST ANALYSIS"
echo "============================="
echo ""

# 1. Identify hotspots (files with high change + complexity)
echo "Analyzing hotspots..."
hotspot_count=$(run_hotspot_analysis | grep "CRITICAL\|HIGH" | wc -l)
hotspot_changes=$(calculate_total_changes_to_hotspots)

# 2. Calculate productivity loss
echo "Calculating productivity impact..."
# Assume hotspots take 2.5x longer to modify
time_tax=1.5  # 2.5x - 1.0x baseline
productivity_loss_hours=$(echo "$hotspot_changes * 2 * $time_tax" | bc)
productivity_loss_cost=$(echo "$productivity_loss_hours * $HOURLY_RATE" | bc)

echo "  Productivity Loss: $productivity_loss_hours hours = \$$productivity_loss_cost"

# 3. Calculate defect risk
echo "Calculating defect risk..."
# Research: hotspots have 3x higher defect rate
defect_multiplier=3
expected_defects=$(echo "$hotspot_count * $defect_multiplier" | bc)
defect_risk_cost=$(echo "$expected_defects * $DEFECT_COST" | bc)

echo "  Defect Risk: $expected_defects defects = \$$defect_risk_cost"

# 4. Calculate coordination overhead
echo "Analyzing coordination costs..."
high_coord_files=$(find_files_with_many_contributors 7)
coord_overhead_hours=$(echo "$high_coord_files * 6 * 2" | bc) # 6 changes/mo, 2hr/change
coord_cost=$(echo "$coord_overhead_hours * $HOURLY_RATE * 12" | bc)

echo "  Coordination Overhead: $coord_overhead_hours hours/mo = \$$coord_cost/year"

# 5. Total annual debt cost
total_cost=$(echo "$productivity_loss_cost + $defect_risk_cost + $coord_cost" | bc)

echo ""
echo "TOTAL ANNUAL TECHNICAL DEBT COST: \$$total_cost"
echo ""

# 6. Calculate debt-to-development ratio
total_capacity=$(echo "$TEAM_SIZE * 2000" | bc) # 2000 hours/year per dev
debt_hours=$(echo "$productivity_loss_hours + $coord_overhead_hours * 12" | bc)
debt_ratio=$(echo "scale=1; $debt_hours / $total_capacity * 100" | bc)

echo "Debt-to-Development Ratio: ${debt_ratio}%"
echo "This represents approximately $(echo "scale=1; $TEAM_SIZE * $debt_ratio / 100" | bc) FTE spent on debt"

Business Translation Template

Use this template for executive presentations:

## Technical Debt Business Impact

**Executive Summary**

We are spending approximately $[TOTAL_COST]/year on technical debt.
This represents [X]% of engineering capacity, equivalent to [Y] full-time
developers doing nothing but managing complexity and fixing avoidable bugs.

### What This Means

**Development Slowdown**
Features take [X]% longer to ship due to complex, hard-to-change code.
- Impact: [N] fewer features shipped per year
- Value: ~$[VALUE] in missed opportunities

**Quality Issues**
We experience [X]x more bugs in certain areas, leading to:
- Customer escalations and churn
- Emergency fixes that disrupt planned work
- Impact: $[DEFECT_COST] in incident costs annually

**Team Inefficiency**
Developers spend [X] hours per month coordinating changes in complex areas
- Impact: $[COORD_COST] in coordination overhead
- Symptom: Merge conflicts, duplicate work, meeting overhead

**Missed Opportunities**
Could build [N] additional features per year if not burdened by technical debt
- Impact: $[OPP_COST] in potential value

### Recommendation

Invest $[INVESTMENT] ([X] months, [Y] developers) to refactor the
top [N] problem areas.

Expected outcomes:
- Reduce ongoing debt cost by [X]% ($[SAVINGS]/year)
- Break even in [X] months
- Accelerate feature development by [Y]%
- Reduce production incidents by [Z]%

### Cost of Inaction

If unaddressed, technical debt compounds at ~15-20% annually.
By end of [YEAR], debt will cost $[PROJECTED_COST]/year, consuming
[X]% of engineering capacity.

Common Mistakes

Mistake 1: Too precise with estimates

Problem: Claiming exact costs ($327,450.23) when formulas involve assumptions.

# ❌ BAD: False precision
"Technical debt costs exactly $327,450.23 per year"

# ✅ GOOD: Ranges with rounding
"Technical debt costs approximately $300-350K per year"

Fix: Always use ranges and round numbers. This maintains credibility with executives.

Mistake 2: Not citing research sources

Problem: Saying "this is expensive" without backing it up.

Fix: Always cite: "Microsoft Research shows hotspots have 4-9x higher defect rates." Reference the research that backs your multipliers.

Mistake 3: Using pessimistic multipliers everywhere

Problem: Applying worst-case (9x defect rate) to every file.

Fix: Use conservative estimates (2-3x) unless you have specific data. "We estimate 2-3x defects (Google research) but could be as high as 4-9x (Microsoft Research)."

Mistake 4: Forgetting opportunity cost

Problem: Only counting direct costs (time wasted, bugs).

Fix: Always include opportunity cost. "We could deliver 3-4 more features per year" resonates with business stakeholders.

Mistake 5: Not explaining assumptions

Problem: Presenting estimates without showing your work.

Fix: Explicitly state: "Based on $100/hour developer cost, 10-person team, industry average $5K per defect..."

Real-World Impact

Example: Startup Velocity Crisis

Context: 8-person team, 2-year codebase, velocity dropped 30% in 6 months

Analysis:

• Productivity Loss: $120K/year (wasted time on complex code)
• Defect Risk: $200K/year (3 files generating 60% of bugs)
• Coordination: $45K/year
• Total Debt Cost: $365K/year

Recommendation: 2-week sprint on top 3 hotspots ($20K investment)

ROI:

• Expected bug reduction: 40% = $80K savings
• Expected productivity gain: 15% = $50K value
• Annual savings: $130K
• ROI: 550%, break-even: 2 months

Outcome: CEO approved, velocity recovered in 3 months, debt cost reduced to $240K/year.

Example: Enterprise M&A Audit

Context: 50-person team, 5-year codebase, acquisition due diligence

Analysis:

• $2.1M/year total debt cost
• Truck factor: 3 (risky for 50-person team)
• 18 critical hotspots with single ownership
• Test suite: 45% brittle tests

Recommendation: 6-month quality initiative post-acquisition ($500K)

Impact: Acquisition proceeded, debt issues priced into deal (~$2M discount)

⚡ After Running Debt Quantification (DO THIS)

Immediately suggest these next steps to the user:

1. Identify the sources (use forensic-hotspot-finder)

   • Which files are causing the costs?
   • Where should we invest first?

2. Calculate ROI (use forensic-refactoring-roi)

   • What's the payback period?
   • Which fixes have highest ROI?

3. Check ownership risk (use forensic-knowledge-mapping)

   • Add risk premium for single-owner files
   • Calculate knowledge transfer costs

4. Track trends (use forensic-complexity-trends)

   • Is debt growing or shrinking?
   • Measure improvement quarterly

Example: Complete Debt Quantification Workflow

"Using forensic-debt-quantification formulas, I've calculated the annual cost:

TOTAL TECHNICAL DEBT COST: $465,000/year

Breakdown:
- Productivity Loss: $180,000 (1,800 hours at $100/hr)
- Defect Risk: $225,000 (Microsoft Research: 4-9x defect rates)
- Coordination: $60,000 (Google: >9 contributors = overhead)

This represents 18% of engineering capacity (approximately 2 FTE).

RECOMMENDED NEXT STEPS:
1. Identify hotspots (forensic-hotspot-finder) - Which files drive these costs?
2. Calculate ROI (forensic-refactoring-roi) - Where to invest first?
3. Present to stakeholders with business case

Would you like me to proceed with identifying the specific files causing these costs?"

Always provide ROI context - executives need to know the payback, not just the cost.

Cost Estimation Guidelines

Conservative Approach (Recommended)

Use these conservative multipliers for credibility:

• Productivity impact: 1.5-2x time increase
• Defect rate: 2-3x baseline
• Defect cost: $3,000-5,000 (unless data says otherwise)
• Developer rate: $80-100/hour (loaded cost)

When to Use Higher Multipliers

Only use aggressive multipliers (4x, 9x) when:

• You have internal data supporting it
• The context clearly justifies it (e.g., critical payment code)
• You're showing a range: "2-9x higher defect rate depending on complexity"

Validating Your Estimates

After calculating, sanity check:

• Does total cost seem reasonable for team size?
• Is debt-to-development ratio believable (10-30% typical)?
• Would reducing this debt save the estimated amount?
• Do stakeholders recognize the problems described?

Related Patterns

• Cost-Benefit Analysis: Compare debt reduction cost vs ongoing debt cost
• Risk Management: High-cost + high-probability = top priority
• Amortization: Debt compounds over time if not addressed
• Technical Bankruptcy: When debt cost exceeds development capacity