菜单
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
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| 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 |
State explicitly: "Using forensic-refactoring-roi pattern"
Then follow these steps:
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:
Core principle: Refactoring ROI = (Annual Savings / Investment Cost) × 100%. High ROI = High impact + Low effort.
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.
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.
| 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 |
| 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) |
| 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% |
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.
For each candidate:
# 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)
Expected improvements by refactoring type:
# 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.
For each candidate:
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
Sort by priority:
# 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]
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
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...]
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)
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
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
Problem: Using best-case effort without accounting for unknowns.
# ❌ 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.
Problem: Calculating effort without input from developers who'll do the work.
# ❌ 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.
Problem: Planning refactorings without considering sequencing requirements.
# ❌ 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).
Problem: Making ROI estimates but never validating if they were accurate.
Fix: After refactoring, measure:
Immediately suggest these next steps to the user:
Validate effort with team (critical for credibility)
Check current costs (use forensic-debt-quantification)
Correlate with hotspots (use forensic-hotspot-finder)
Track refactoring outcomes (use forensic-complexity-trends)
"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 outcomes (forensic-complexity-trends)
Would you like me to prepare a detailed roadmap for Phase 1?"
Always provide this integration guidance - ROI analysis is most effective when combined with team validation and forensic data.
Balance quick wins with strategic investments:
Allocate refactoring budget across risk profiles:
Quick Wins (60% of budget):
- High ROI, low risk
- Build momentum and trust
- Validate methodology
Strategic Investments (30% of budget):
- Moderate ROI, architectural impact
- Long-term value
- Enables future refactorings
Experiments (10% of budget):
- Uncertain ROI
- Learning opportunities
- Innovation attempts
Test how estimates change with assumptions:
Scenario Analysis for processor.js:
Base Case:
Effort: 80 hours
Savings: $35K/year
ROI: 438%
Pessimistic (20% worse):
Effort: 96 hours (+20%)
Savings: $28K/year (-20%)
ROI: 292% (still > 150%, still worth it)
Optimistic (20% better):
Effort: 64 hours (-20%)
Savings: $42K/year (+20%)
ROI: 656%
Conclusion: Even in pessimistic case, ROI > 150% - proceed
Measure portfolio performance over time:
Quarterly Refactoring Results:
Q1 2024:
Investment: $10,900
Actual Savings (so far): $52,000 annualized
ROI: 477% (target was 560%)
Accuracy: 85% (good!)
Q2 2024:
Investment: $22,500
Actual Savings (so far): $65,000 annualized
ROI: 289% (target was 347%)
Accuracy: 83%
Learning: Effort estimates good, savings slightly optimistic
Adjustment: Use 0.9x multiplier on future savings estimates
Key studies:
Microsoft Research (2016): Refactoring productivity impact
Google Engineering (2018): Defect reduction from refactoring
Conway's Law Studies (2015): Coordination overhead
Agile Economics (Reinertsen, 2009): Cost of delay
Why ROI matters: Translates technical arguments into business language. Executives understand payback periods and ROI percentages.
ROI analysis requires data from:
Why: ROI analysis synthesizes all forensic data into actionable priorities with business justification.
Use when planning architecture refactoring, understanding cross-module dependencies, discovering hidden dependencies, finding shotgun surgery patterns, or identifying files that change together - reveals temporal coupling and architectural violations using git history analysis
Use when monitoring code quality over time, measuring refactoring impact, tracking if complexity is improving or worsening, or validating technical debt work - tracks complexity metrics across git history identifying improving, stable, or deteriorating files
Use when investigating merge conflicts, reducing communication overhead, detecting modules with high coordination complexity, or identifying files edited by many contributors and cross-team - reveals coordination bottlenecks and team communication issues
Use when justifying technical debt to executives, calculating the cost of quality issues, translating tech metrics to business language, or planning quality budgets - uses research-backed formulas (2-3x defects, productivity multipliers) to convert code problems into dollars and ROI
Use when planning refactoring priorities, investigating recurring bugs, identifying which files cause the most bugs, or determining problem areas to fix - identifies high-risk files by combining git change frequency with code complexity using research-backed formula (4-9x defect rates)
Use when assessing team resilience, planning for developer departures, calculating bus/truck factor, identifying knowledge silos, or evaluating organizational risk - maps code ownership from git history and identifies single points of failure using research-backed thresholds (>80% ownership = silo)