forensic-refactoring-roi
Use when planning refactoring sprints, prioritizing technical debt backlog, justifying refactoring investment to executives, or creating data-driven roadmaps - calculates return on investment using effort-impact matrices and research-backed formulas
- Category: discovered
- Tags: github, community
- Version: 1.0.0
- Author: walid
- Downloads: 0
- Updated: 2025-11-22
Download the latest version (v1.0.0) from this page.
SKILL.md
---
name: forensic-refactoring-roi
description: Use when planning refactoring sprints, prioritizing technical debt backlog, justifying refactoring investment to executives, or creating data-driven roadmaps - calculates return on investment using effort-impact matrices and research-backed formulas
---
# Forensic Refactoring ROI Analysis
## 🎯 When You Use This Skill
**State explicitly**: "Using forensic-refactoring-roi pattern"
**Then follow these steps**:
1. Calculate **current annual cost** for each candidate (from debt quantification)
2. Estimate **refactoring effort** using LOC and complexity multipliers
3. Calculate **ROI percentage**: (Annual Savings / Investment) × 100
4. Cite **research** when presenting ROI (refactoring yields 30-70% productivity gains)
5. Suggest **integration** with hotspot/trends analysis for complete picture
## Overview
Refactoring ROI analysis prioritizes technical debt work by calculating the return on investment for each refactoring candidate. Unlike simple prioritization (just complexity or change frequency), ROI analysis provides:
- **Business justification** - Translate refactoring to dollars and payback period
- **Prioritized roadmap** - Which refactorings deliver highest value fastest
- **Effort-impact matrices** - Visual comparison of quick wins vs major projects
- **Risk-adjusted estimates** - Account for uncertainty and business criticality
- **Phased execution plans** - Multi-sprint roadmaps with clear milestones
**Core principle**: Refactoring ROI = (Annual Savings / Investment Cost) × 100%. High ROI = High impact + Low effort.
## When to Use
- Planning quarterly refactoring sprints (which files to tackle?)
- Justifying technical debt work to executives or product managers
- Prioritizing backlog items with data (not gut feelings)
- Creating multi-sprint refactoring roadmaps
- Evaluating competing refactoring proposals
- Building business case for developer time allocation
- Post-refactoring validation (did we get expected ROI?)
## When NOT to Use
- No cost data available (requires debt quantification first)
- Insufficient effort estimation expertise (need team input)
- When refactoring is mandatory (security, compliance) - just do it
- Greenfield projects (no baseline costs to compare)
- For very small refactorings (<4 hours) - overhead not worth it
## Core Pattern
### ⚡ THE ROI CALCULATION FORMULA (USE THIS)
**This is the research-backed ROI formula - don't create custom approaches**:
```
ROI (%) = (Annual Savings / Investment Cost) × 100
Where:
Annual Savings = Current Annual Cost - Post-Refactoring Annual Cost
Investment Cost = Effort (hours) × Hourly Rate
Break-Even Period (months) = (Investment Cost / Annual Savings) × 12
Prioritization:
- QUICK WINS: ROI > 500%, Break-even < 3 months
- HIGH PRIORITY: ROI > 300%, Break-even < 6 months
- STRATEGIC: ROI > 150%, Break-even < 12 months
- LOW PRIORITY: ROI < 150% or Break-even > 12 months
```
**Effort estimation**:
```
Base Effort (hours) = (LOC / 100) × Complexity Multiplier
Complexity Multipliers:
- Simple: 0.5x (well-structured, clear refactoring path)
- Moderate: 1.0x (typical complexity)
- High: 2.0x (nested logic, unclear structure)
- Critical: 3.0x (business-critical, high risk)
Adjustment Factors (additive):
+ Low test coverage: +50% (must add tests)
+ High dependencies: +30% (coordination required)
+ Business critical: +40% (extra validation)
+ Team unfamiliar: +25% (learning curve)
- Good docs: -20% (easier to understand)
```
**Critical**: Always use **risk-adjusted ROI** for business-critical systems by multiplying by success probability.
### 📊 Research Benchmarks (CITE THESE)
**Always reference the research when presenting ROI**:
| Outcome | Impact | Source | When to Cite |
|---------|--------|--------|--------------|
| Productivity gains | **30-70%** faster changes | Microsoft Research | "Refactoring typically yields 30-70% productivity improvement (Microsoft)" |
| Defect reduction | **40-60%** fewer bugs | Google eng practices | "Research shows 40-60% defect reduction after refactoring (Google)" |
| Coordination savings | **50-70%** less overhead | Conway's Law studies | "Better boundaries reduce coordination by 50-70% (Conway)" |
**Always cite the source** when presenting ROI to justify investment in refactoring.
## Quick Reference
### ROI Classification
| ROI % | Break-even | Classification | Action |
|-------|------------|----------------|--------|
| **>500%** | <3 months | QUICK WIN | Do immediately |
| **300-500%** | 3-6 months | HIGH PRIORITY | Schedule next sprint |
| **150-300%** | 6-12 months | STRATEGIC | Plan for quarter |
| **<150%** | >12 months | LOW PRIORITY | Defer or skip |
### Effort-Impact Quadrants
| Quadrant | Description | Priority | Example |
|----------|-------------|----------|---------|
| **High Impact, Low Effort** | QUICK WINS | ★★★★★ | Extract config to module (3 days, $20K/year savings) |
| **High Impact, High Effort** | STRATEGIC | ★★★★☆ | Refactor payment system (2 weeks, $35K/year savings) |
| **Low Impact, Low Effort** | FILL-INS | ★★☆☆☆ | Clean up utility file (2 days, $5K/year savings) |
| **Low Impact, High Effort** | AVOID | ☆☆☆☆☆ | Rewrite legacy UI (4 weeks, $8K/year savings) |
### Typical Improvement Percentages
| Refactoring Type | Productivity | Defects | Coordination |
|------------------|--------------|---------|--------------|
| **Simple extract** | 30-40% | 20-30% | 10-20% |
| **Major restructure** | 50-70% | 40-60% | 50-70% |
| **Add tests** | 10-20% | 40-60% | 5-10% |
| **Better boundaries** | 20-30% | 10-20% | 50-70% |
## Implementation
### Step 1: Gather Input Data
**Required inputs** (from other forensic skills):
```
For each refactoring candidate, need:
1. Current Annual Cost (from forensic-debt-quantification):
- Productivity loss: $X/year
- Defect risk: $Y/year
- Coordination overhead: $Z/year
- Total: $(X+Y+Z)/year
2. File Metrics (from forensic-hotspot-finder):
- Lines of code
- Complexity score
- Change frequency
- Bug history
3. Team Context:
- Hourly rate (default: $100)
- Available capacity
- Risk tolerance
```
**Integration point**: Run debt-quantification and hotspot-finder BEFORE this skill.
### Step 2: Estimate Refactoring Effort
**For each candidate**:
```python
# Pseudocode for effort estimation
def estimate_effort(file):
# Base calculation
base_hours = (file.loc / 100) * get_complexity_multiplier(file)
# Apply adjustment factors
adjustments = 1.0
if file.test_coverage < 50:
adjustments += 0.50 # Must add tests
if file.dependency_count > 10:
adjustments += 0.30 # High coordination
if file.is_business_critical:
adjustments += 0.40 # Extra validation
if team.familiarity < 0.5:
adjustments += 0.25 # Learning curve
if file.has_good_docs:
adjustments -= 0.20 # Easier to understand
total_hours = base_hours * adjustments
return total_hours
def get_complexity_multiplier(file):
if file.complexity_score < 20:
return 0.5 # Simple
elif file.complexity_score < 50:
return 1.0 # Moderate
elif file.complexity_score < 80:
return 2.0 # High
else:
return 3.0 # Critical
```
**Example calculation**:
```
File: auth/authentication.js
- LOC: 800
- Complexity: High (score 75) → 2.0x multiplier
- Test coverage: 30% (low) → +50%
- Business critical: Yes → +40%
Base effort: (800 / 100) × 2.0 = 16 hours
Adjusted: 16 × (1 + 0.5 + 0.4) = 16 × 1.9 = 30.4 hours (~4 days)
```
### Step 3: Estimate Post-Refactoring Savings
**Expected improvements by refactoring type**:
```python
# Typical improvement percentages (conservative estimates)
def estimate_savings(current_cost, refactoring_type):
# Break down current cost
productivity_cost = current_cost.productivity
defect_cost = current_cost.defects
coordination_cost = current_cost.coordination
# Apply improvement percentages based on type
if refactoring_type == "simple_extract":
prod_improvement = 0.35 # 35% faster changes
defect_improvement = 0.25 # 25% fewer bugs
coord_improvement = 0.15 # 15% less coordination
elif refactoring_type == "major_restructure":
prod_improvement = 0.60 # 60% faster changes
defect_improvement = 0.50 # 50% fewer bugs
coord_improvement = 0.60 # 60% less coordination
# Calculate savings
productivity_savings = productivity_cost * prod_improvement
defect_savings = defect_cost * defect_improvement
coordination_savings = coordination_cost * coord_improvement
total_annual_savings = (productivity_savings +
defect_savings +
coordination_savings)
return total_annual_savings
```
**Conservative approach**: Always use lower end of research ranges (30% vs 70%) for credibility.
### Step 4: Calculate ROI
**For each candidate**:
```python
def calculate_roi(candidate, hourly_rate=100):
# Investment
investment = candidate.effort_hours * hourly_rate
# Annual savings
annual_savings = candidate.current_cost - candidate.post_refactor_cost
# Basic ROI
roi_pct = (annual_savings / investment) * 100
# Break-even period
breakeven_months = (investment / annual_savings) * 12
# Risk-adjusted ROI
success_probability = calculate_success_probability(candidate)
risk_adjusted_roi = roi_pct * success_probability
return {
'investment': investment,
'annual_savings': annual_savings,
'roi_pct': roi_pct,
'breakeven_months': breakeven_months,
'risk_adjusted_roi': risk_adjusted_roi,
'success_probability': success_probability
}
def calculate_success_probability(candidate):
prob = 1.0
# Test coverage factor
if candidate.test_coverage > 80:
prob *= 0.95
elif candidate.test_coverage > 50:
prob *= 0.85
else:
prob *= 0.70
# Complexity factor
if candidate.complexity == "simple":
prob *= 0.95
elif candidate.complexity == "moderate":
prob *= 0.90
else:
prob *= 0.80
# Criticality factor
if candidate.is_critical:
prob *= 0.75
else:
prob *= 0.90
return prob
```
### Step 5: Prioritize and Create Roadmap
**Sort by priority**:
```python
# Primary sort: ROI percentage (descending)
# Secondary sort: Break-even period (ascending)
candidates_sorted = sorted(candidates,
key=lambda c: (c.roi_pct, -c.breakeven_months),
reverse=True
)
# Group into phases
quick_wins = [c for c in candidates_sorted
if c.roi_pct > 500 and c.breakeven_months < 3]
high_priority = [c for c in candidates_sorted
if 300 <= c.roi_pct <= 500 and c.breakeven_months < 6]
strategic = [c for c in candidates_sorted
if 150 <= c.roi_pct < 300 and c.breakeven_months < 12]
```
## Output Format
### 1. Executive Summary
```
Refactoring ROI Analysis (forensic-refactoring-roi pattern)
Candidates Analyzed: 10 files
Current Total Debt Cost: $245,000/year
Potential Total Savings: $154,000/year (if all refactored)
Total Investment Required: $42,400 (18 weeks)
Research shows refactoring typically yields 30-70% productivity improvement (Microsoft).
RECOMMENDED PRIORITIES:
Phase 1 - Quick Wins (3 weeks, $10,900):
ROI: 560%, Break-even: 2.1 months
Files: config.js, authentication.js, users.js, validation.js
Phase 2 - High Impact (7 weeks, $22,500):
ROI: 347%, Break-even: 3.5 months
Files: processor.js, router.js, queries.js, user.js
Phase 3 - Strategic (8 weeks, $9,000):
ROI: 167%, Break-even: 7 months
Files: old-api.js, App.tsx, remaining items
```
### 2. Top Candidates Table (with ROI details)
```
QUICK WINS (Highest ROI):
1. core/config.js ROI: 833%
┌───────────────────────────────────────────────────────────┐
│ Current Annual Cost: $20,000 │
│ Refactoring Effort: 24 hours (3 days) │
│ Investment: $2,400 │
│ Annual Savings: $20,000 - $5,000 = $15,000 │
│ ROI: ($15K / $2.4K) × 100 = 625% │
│ Break-even: 1.9 months │
│ │
│ Cost Breakdown (savings): │
│ - Productivity: $8,000 → $2,000 (75% improvement) │
│ - Defects: $9,000 → $2,500 (72% reduction) │
│ - Coordination: $3,000 → $500 (83% reduction) │
│ │
│ Refactoring Plan: │
│ 1. Split into domain-specific modules (12h) │
│ 2. Add schema validation (6h) │
│ 3. Create documentation (4h) │
│ 4. Migrate usages (2h) │
│ │
│ Risk: LOW (good test coverage, non-critical) │
│ Success Probability: 81% │
│ │
│ RECOMMENDATION: START HERE - Excellent ROI, low risk │
└───────────────────────────────────────────────────────────┘
2. auth/authentication.js ROI: 733%
[Similar detailed breakdown...]
```
### 3. Effort-Impact Matrix Visualization
```
Effort-Impact Matrix:
HIGH IMPACT ($30K+ savings)
│
│ [processor.js] [router.js]
│ $35K, 80h $15K, 50h
│ 2 weeks 1 week
│
│ [authentication.js] [users.js] [queries.js]
│ $22K, 30h $14K, 20h $16K, 60h
│ 4 days 2.5 days 1.5 weeks
│
│ [config.js] [user.js] [validation.js]
│ $20K, 24h $12K, 35h $5K, 15h
│ 3 days 4 days 2 days
├──────────────────────────────────────────────────► LOW EFFORT
│ to HIGH EFFORT
│ [App.tsx] [old-api.js]
│ $5K, 30h $8K, 40h
│ 4 days 1 week
│
LOW IMPACT (<$10K savings)
START WITH TOP-LEFT (Quick Wins):
✅ config.js (3 days, $20K/year, 833% ROI)
✅ authentication.js (4 days, $22K/year, 733% ROI)
✅ users.js (2.5 days, $14K/year, 700% ROI)
```
### 4. Phased Roadmap with Milestones
```
PHASE 1: QUICK WINS (Weeks 1-3)
Week 1: config.js (3 days, $20K/year savings)
↳ Milestone: Foundation for downstream improvements
Week 2: authentication.js (4 days, $22K/year savings)
+ users.js (2.5 days, $14K/year savings)
↳ Milestone: Secure critical auth path
Week 3: validation.js (2 days, $5K/year savings)
↳ Milestone: Complete quick wins phase
Phase 1 Total:
Investment: $10,900 (11.5 days)
Annual Savings: $61,000
ROI: 560%
Cumulative Break-even: 2.1 months
---
PHASE 2: HIGH-IMPACT SYSTEMS (Weeks 4-10)
Weeks 4-5: processor.js (2 weeks, $35K/year savings)
↳ Milestone: CRITICAL payment system stabilized
Weeks 6-7: router.js (1 week, $15K/year savings)
↳ Milestone: API architecture improved
Weeks 8-9: queries.js (1.5 weeks, $16K/year savings)
↳ Milestone: Database layer optimized
Week 10: user.js (4 days, $12K/year savings)
↳ Milestone: User domain refactored
Phase 2 Total:
Investment: $22,500 (7 weeks)
Annual Savings: $78,000
ROI: 347%
Cumulative Break-even: 3.5 months
Expected Impact (Microsoft Research): 30-70% productivity improvement
```
### 5. Risk Assessment Per Candidate
```
HIGH-RISK CANDIDATES (Require Extra Care):
processor.js (Payment Processing):
Risks:
⚠️ Revenue impact (business-critical)
⚠️ Complex business logic
⚠️ Multiple payment provider integrations
Mitigation Strategy:
✅ Feature flag rollout (gradual deployment)
✅ Shadow testing (run old + new in parallel)
✅ >90% test coverage requirement
✅ Business stakeholder approval
✅ Rollback plan documented
Success Probability: 42% (adjusted for risk)
Risk-Adjusted ROI: 438% × 0.42 = 184%
RECOMMENDATION: HIGH PRIORITY but plan carefully
```
## Common Mistakes
### Mistake 1: Optimistic effort estimates
**Problem**: Using best-case effort without accounting for unknowns.
```bash
# ❌ BAD: Overly optimistic
effort = loc / 100 # Assumes everything is simple
# ✅ GOOD: Apply complexity and risk multipliers
base_effort = loc / 100
complexity_mult = 2.0 # High complexity
risk_adjustments = 1.0 + 0.5 + 0.4 # Low tests + critical
total_effort = base_effort * complexity_mult * risk_adjustments
```
**Fix**: **Always apply adjustment factors** for test coverage, criticality, dependencies. Use conservative estimates.
### Mistake 2: Not validating with team
**Problem**: Calculating effort without input from developers who'll do the work.
```bash
# ❌ BAD: Analyst makes all estimates
roi_analyst_calculates_all()
# ✅ GOOD: Validate with engineering team
draft_estimates = calculate_initial_roi()
team_review = validate_with_engineers(draft_estimates)
final_estimates = adjust_based_on_feedback(team_review)
```
**Fix**: **Always validate effort estimates** with the team. They know the codebase better than formulas.
### Mistake 3: Ignoring dependencies
**Problem**: Planning refactorings without considering sequencing requirements.
```bash
# ❌ BAD: Treat all candidates as independent
sort_by_roi_only()
# ✅ GOOD: Account for dependencies
identify_dependencies(candidates)
sequence_considering_prerequisites()
```
**Fix**: **Always check dependencies** - some refactorings must precede others (e.g., config before router).
### Mistake 4: Not tracking actual results
**Problem**: Making ROI estimates but never validating if they were accurate.
**Fix**: After refactoring, measure:
- Did complexity decrease as expected?
- Did change time improve?
- Did defect rate drop?
- Document for future estimation improvement
## ⚡ After Running ROI Analysis (DO THIS)
**Immediately suggest these next steps to the user**:
1. **Validate effort with team** (critical for credibility)
- Share estimates with engineers
- Get feedback on complexity multipliers
- Adjust based on team knowledge
2. **Check current costs** (use **forensic-debt-quantification**)
- If not already done, quantify debt for each candidate
- Annual costs required for ROI calculation
- May reveal different priorities
3. **Correlate with hotspots** (use **forensic-hotspot-finder**)
- Hotspots + High ROI = strongest candidates
- Verify change frequency assumptions
- Ensure focusing on actual problem areas
4. **Track refactoring outcomes** (use **forensic-complexity-trends**)
- After refactoring, re-run trends analysis
- Validate productivity improvements
- Document lessons for future estimates
### Example: Complete ROI Analysis Workflow
```
"Using forensic-refactoring-roi pattern, I analyzed 10 refactoring candidates.
EXECUTIVE SUMMARY:
Quick Wins (3 weeks, $10,900 investment):
├─ config.js: 833% ROI, 1.9mo break-even
├─ authentication.js: 733% ROI, 1.6mo break-even
├─ users.js: 700% ROI, 1.7mo break-even
└─ validation.js: 333% ROI, 3.6mo break-even
Expected Annual Savings: $61,000
Expected Impact: 30-70% productivity improvement (Microsoft Research)
HIGH-RISK ITEM: processor.js
ROI: 438% BUT business-critical (payment processing)
Requires: feature flags, shadow testing, >90% coverage
Success probability: 42% (risk-adjusted ROI: 184%)
RECOMMENDED NEXT STEPS:
1. Validate estimates with engineering team - Get buy-in on effort
2. Check debt costs (forensic-debt-quantification) - Confirm annual costs
3. Cross-check hotspots (forensic-hotspot-finder) - Align priorities
4. After refactoring: Track out