technical-debt-management skill

---
name: Technical Debt Management
description: Systematic technical debt quantification and management using SQALE methodology with value-effort prioritization, phased paydown roadmaps, and prevention strategies. Use when technical debt unmeasured or subjective, need objective prioritization, planning refactoring work, establishing debt prevention practices, or tracking debt trends over time. Provides 6 methodology components (measurement with SQALE index, categorization with code smell taxonomy, prioritization with value-effort matrix, phased paydown roadmap, trend tracking system, prevention guidelines), 3 patterns (SQALE-based quantification, code smell taxonomy mapping, value-effort prioritization), 3 principles (high-value low-effort first, SQALE provides objective baseline, complexity drives maintainability debt). Validated with 4.5x speedup vs manual approach, 85% transferability across languages (Go, Python, JavaScript, Java, Rust), SQALE industry-standard methodology.
allowed-tools: Read, Write, Edit, Bash, Grep, Glob
---

# Technical Debt Management

**Transform subjective debt assessment into objective, data-driven paydown strategy with 4.5x speedup.**

> Measure what matters. Prioritize by value. Pay down strategically. Prevent proactively.

---

## When to Use This Skill

Use this skill when:
- 📊 **Unmeasured debt**: Technical debt unknown or subjectively assessed
- 🎯 **Need prioritization**: Many debt items, unclear which to tackle first
- 📈 **Planning refactoring**: Need objective justification and ROI analysis
- 🚨 **Debt accumulation**: Debt growing but no tracking system
- 🔄 **Prevention lacking**: Reactive debt management, no proactive practices
- 📋 **Objective reporting**: Stakeholders need quantified debt metrics

**Don't use when**:
- ❌ Debt already well-quantified with SQALE or similar methodology
- ❌ Codebase very small (<1K LOC, minimal debt accumulation)
- ❌ No refactoring capacity (debt measurement without action is wasteful)
- ❌ Tools unavailable (need complexity, coverage, duplication analysis tools)

---

## Quick Start (30 minutes)

### Step 1: Calculate SQALE Index (15 min)

**SQALE Formula**:
```
Development Cost = LOC / 30  (30 LOC/hour productivity)
Technical Debt = Remediation Cost (hours)
TD Ratio = Technical Debt / Development Cost × 100%
```

**SQALE Ratings**:
- A (Excellent): ≤5% TD ratio
- B (Good): 6-10%
- C (Moderate): 11-20%
- D (Poor): 21-50%
- E (Critical): >50%

**Example** (meta-cc):
```
LOC: 12,759
Development Cost: 425.3 hours
Technical Debt: 66.0 hours
TD Ratio: 15.52% (Rating: C - Moderate)
```

### Step 2: Categorize Debt (10 min)

**SQALE Code Smell Taxonomy**:
1. **Bloaters**: Long methods, large classes (complexity debt)
2. **Change Preventers**: Shotgun surgery, divergent change (flexibility debt)
3. **Reliability Issues**: Test coverage gaps, error handling (quality debt)
4. **Couplers**: Feature envy, inappropriate intimacy (coupling debt)
5. **Dispensables**: Duplicate code, dead code (maintainability debt)

**Example Breakdown**:
- Complexity: 54.5 hours (82.6%)
- Coverage: 10.0 hours (15.2%)
- Duplication: 1.0 hours (1.5%)

### Step 3: Prioritize with Value-Effort Matrix (5 min)

**Four Quadrants**:
```
High Value, Low Effort  → Quick Wins (do first)
High Value, High Effort → Strategic (plan carefully)
Low Value, Low Effort   → Opportunistic (do when convenient)
Low Value, High Effort  → Avoid (skip unless critical)
```

**Quick Wins Example**:
- Fix error capitalization (0.5 hours)
- Increase test coverage for small module (2.0 hours)

---

## Six Methodology Components

### 1. Measurement Framework (SQALE)

**Objective**: Quantify technical debt objectively using industry-standard SQALE methodology

**Three Calculations**:

**A. Development Cost**:
```
Development Cost = LOC / Productivity
Productivity = 30 LOC/hour (SQALE standard)
```

**B. Remediation Cost** (Complexity Example):
```
Graduated Thresholds:
- Low complexity (≤10): 0 hours
- Medium complexity (11-15): 0.5 hours per function
- High complexity (16-25): 1.0 hours per function
- Very high (26-50): 2.0 hours per function
- Extreme (>50): 4.0 hours per function
```

**C. Technical Debt Ratio**:
```
TD Ratio = (Total Remediation Cost / Development Cost) × 100%
SQALE Rating = Map TD Ratio to A-E scale
```

**Tools**:
- Go: gocyclo, gocov, golangci-lint
- Python: radon, pylint, pytest-cov
- JavaScript: eslint, jscpd, nyc
- Java: PMD, JaCoCo, CheckStyle
- Rust: cargo-geiger, clippy

**Output**: SQALE Index Report (total debt, TD ratio, rating, breakdown by category)

**Transferability**: 100% (SQALE formulas language-agnostic)

---

### 2. Categorization Framework (Code Smells)

**Objective**: Map metrics to SQALE code smell taxonomy for prioritization

**Five SQALE Categories**:

**1. Bloaters** (Complexity Debt):
- Long methods (cyclomatic complexity >10)
- Large classes (>500 LOC)
- Long parameter lists (>5 parameters)
- **Remediation**: Extract method, split class, introduce parameter object

**2. Change Preventers** (Flexibility Debt):
- Shotgun surgery (change requires touching multiple files)
- Divergent change (class changes for multiple reasons)
- **Remediation**: Consolidate logic, introduce abstraction layer

**3. Reliability Issues** (Quality Debt):
- Test coverage gaps (<80% target)
- Missing error handling
- **Remediation**: Add tests, implement error handling

**4. Couplers** (Coupling Debt):
- Feature envy (method uses data from another class more than own)
- Inappropriate intimacy (high coupling between modules)
- **Remediation**: Move method, reduce coupling

**5. Dispensables** (Maintainability Debt):
- Duplicate code (>3% duplication ratio)
- Dead code (unreachable functions)
- **Remediation**: Extract common code, remove dead code

**Output**: Code Smell Report (smell type, instances, files, remediation cost)

**Transferability**: 80-90% (OO smells apply to OO languages only, others universal)

---

### 3. Prioritization Framework (Value-Effort Matrix)

**Objective**: Rank debt items by ROI (business value / remediation effort)

**Business Value Assessment** (3 factors):
1. **User Impact**: Does debt affect user experience? (0-10)
2. **Change Frequency**: How often is this code changed? (0-10)
3. **Error Risk**: Does debt cause bugs? (0-10)
4. **Total Value**: Sum of 3 factors (0-30)

**Effort Estimation**:
- Use SQALE remediation cost model
- Factor in testing, code review, deployment time

**Value-Effort Quadrants**:
```
         High Value
         |
 Quick   |   Strategic
  Wins   |
---------|------------- Effort
Opportun-|   Avoid
  istic  |
         |
       Low Value
```

**Priority Ranking**:
1. Quick Wins (high value, low effort)
2. Strategic (high value, high effort) - plan carefully
3. Opportunistic (low value, low effort) - when convenient
4. Avoid (low value, high effort) - skip unless critical

**Output**: Prioritization Matrix (debt items ranked by quadrant)

**Transferability**: 95% (value-effort concept universal, specific values vary)

---

### 4. Paydown Framework (Phased Roadmap)

**Objective**: Create actionable, phased plan for debt reduction

**Four Phases**:

**Phase 1: Quick Wins** (0-2 hours)
- Highest ROI items
- Build momentum, demonstrate value
- Example: Fix lint issues, error capitalization

**Phase 2: Coverage Gaps** (2-12 hours)
- Test coverage improvements
- Prevent regressions, enable refactoring confidence
- Example: Add integration tests, increase coverage to ≥80%

**Phase 3: Strategic Complexity** (12-30 hours)
- High-value, high-effort refactoring
- Address architectural debt
- Example: Consolidate duplicated logic, refactor high-complexity functions

**Phase 4: Opportunistic** (as time allows)
- Low-priority items tackled when working nearby
- Example: Refactor during feature development in same area

**Expected Improvements** (calculate per phase):
```
Phase TD Reduction = Sum of remediation costs in phase
New TD Ratio = (Total Debt - Phase TD Reduction) / Development Cost × 100%
New SQALE Rating = Map new TD ratio to A-E scale
```

**Output**: Paydown Roadmap (4 phases, time estimates, expected TD ratio improvements)

**Transferability**: 100% (phased approach universal)

---

### 5. Tracking Framework (Trend Analysis)

**Objective**: Continuous debt monitoring with early warning alerts

**Five Tracking Components**:

**1. Automated Data Collection**:
- Weekly metrics collection (complexity, coverage, duplication)
- CI/CD integration (collect on every build)

**2. Baseline Storage**:
- Quarterly SQALE snapshots
- Historical comparison (track delta)

**3. Trend Tracking**:
- Time series: TD ratio, complexity, coverage, hotspots
- Identify trends (increasing, decreasing, stable)

**4. Visualization Dashboard**:
- TD ratio over time
- Debt by category (stacked area chart)
- Coverage trends
- Complexity heatmap
- Hotspot analysis (files with most debt)

**5. Alerting Rules**:
- TD ratio increase >5% in 1 month
- Coverage drop >5%
- New high-complexity functions (>25 complexity)
- Duplication spike >3%

**Expected Impact**:
- Visibility: Point-in-time → continuous trends
- Decision making: Reactive → data-driven proactive
- Early warning: Alert before debt spikes

**Output**: Tracking System Design (automation plan, dashboard mockups, alert rules)

**Transferability**: 95% (tracking concept universal, tools vary)

---

### 6. Prevention Framework (Proactive Practices)

**Objective**: Prevent new debt accumulation through gates and practices

**Six Prevention Strategies**:

**1. Pre-Commit Complexity Gates**:
```bash
# Reject commits with functions >15 complexity
gocyclo -over 15 .
```

**2. Test Coverage Requirements**:
- Overall: ≥80%
- New code: ≥90%
- CI/CD gate: Fail build if coverage drops

**3. Static Analysis Enforcement**:
- Zero tolerance for critical issues
- Warning threshold (fail if >10 warnings)

**4. Code Review Checklist** (6 debt prevention items):
- [ ] No functions >15 complexity
- [ ] Test coverage ≥90% for new code
- [ ] No duplicate code (DRY principle)
- [ ] Error handling complete
- [ ] No dead code
- [ ] Architecture consistency maintained

**5. Refactoring Time Budget**:
- Allocate 20% sprint capacity for refactoring
- Opportunistic paydown during feature work

**6. Architecture Review**:
- Quarterly health checks
- Identify architectural debt early
- Plan strategic refactoring

**Expected Impact**:
- TD accumulation: 2%/quarter → <0.5%/quarter
- ROI: 4 days saved per quarter (prevention time << paydown time)

**Output**: Prevention Guidelines (pre-commit hooks, CI/CD gates, code review checklist)

**Transferability**: 85% (specific thresholds vary, practices universal)

---

## Three Extracted Patterns

### Pattern 1: SQALE-Based Debt Quantification

**Problem**: Subjective debt assessment leads to inconsistent prioritization

**Solution**: Use SQALE methodology for objective, reproducible measurement

**Structure**:
1. Calculate development cost (LOC / 30)
2. Calculate remediation cost (graduated thresholds)
3. Calculate TD ratio (remediation / development × 100%)
4. Assign SQALE rating (A-E)

**Benefits**:
- Objective (same methodology, same results)
- Reproducible (industry standard)
- Comparable (across projects, over time)

**Transferability**: 90% (formulas universal, threshold calibration language-specific)

---

### Pattern 2: Code Smell Taxonomy Mapping

**Problem**: Metrics (complexity, duplication) don't directly translate to actionable insights

**Solution**: Map metrics to SQALE code smell taxonomy for clear remediation strategies

**Structure**:
```
Metric → Code Smell → Remediation Strategy
Complexity >10 → Long Method (Bloater) → Extract Method
Duplication >3% → Duplicate Code (Dispensable) → Extract Common Code
Coverage <80% → Test Gap (Reliability Issue) → Add Tests
```

**Benefits**:
- Actionable (smell → remediation)
- Prioritizable (smell severity)
- Educational (developers learn smell patterns)

**Transferability**: 80% (OO smells require adaptation for non-OO languages)

---

### Pattern 3: Value-Effort Prioritization Matrix

**Problem**: Too many debt items, unclear which to tackle first

**Solution**: Rank by ROI using value-effort matrix

**Structure**:
1. Assess business value (user impact + change frequency + error risk)
2. Estimate remediation effort (SQALE model)
3. Plot on matrix (4 quadrants)
4. Prioritize: Quick Wins → Strategic → Opportunistic → Avoid

**Benefits**:
- ROI-driven (maximize value per hour)
- Transparent (stakeholders understand prioritization)
- Flexible (adjust value weights per project)

**Transferability**: 95% (concept universal, specific values vary)

---

## Three Principles

### Principle 1: Pay High-Value Low-Effort Debt First

**Statement**: "Maximize ROI by prioritizing high-value low-effort debt (quick wins) before tackling strategic debt"

**Rationale**:
- Build momentum (early wins)
- Demonstrate value (stakeholder buy-in)
- Free up capacity (small wins compound)

**Evidence**: Quick wins phase (0.5-2 hours) enables larger strategic work

**Application**: Always start paydown roadmap with quick wins

---

### Principle 2: SQALE Provides Objective Baseline

**Statement**: "Use SQALE methodology for objective, reproducible debt measurement to enable data-driven decisions"

**Rationale**:
- Subjective assessment varies by developer
- Objective measurement enables comparison (projects, time periods)
- Industry standard (validated across thousands of projects)

**Evidence**: 4.5x speedup vs manual approach, objective vs subjective

**Application**: Calculate SQALE index before any debt work

---

### Principle 3: Complexity Drives Maintainability Debt

**Statement**: "Complexity debt dominates technical debt (often 70-90%), focus refactoring on high-complexity functions"

**Rationale**:
- High complexity → hard to understand → slow changes → bugs
- Complexity compounds (high complexity attracts more complexity)
- Refactoring complexity has highest impact

**Evidence**: 82.6% of meta-cc debt from complexity (54.5/66 hours)

**Application**: Prioritize complexity reduction in paydown roadmaps

---

## Proven Results

**Validated in bootstrap-012 (meta-cc project)**:
- ✅ SQALE Index: 66 hours debt, 15.52% TD ratio, rating C (Moderate)
- ✅ Methodology: 6/6 components complete (measurement, categorization, prioritization, paydown, tracking, prevention)
- ✅ Convergence: V_instance = 0.805, V_meta = 0.855 (both >0.80)
- ✅ Duration: 4 iterations, ~7 hours
- ✅ Paydown roadmap: 31.5 hours → rating B (8.23%, -47.7% debt reduction)

**Effectiveness Validation**:
- Manual approach: 9 hours (ad-hoc review, subjective prioritization)
- Methodology approach: 2 hours (tool-based, SQALE calculation)
- **Speedup**: 4.5x ✅
- **Accuracy**: Subjective → Objective (SQALE standard)
- **Reproducibility**: Low → High

**Transferability Validation** (5 languages analyzed):
- Go: 90% transferable (native)
- Python: 85% (tools: radon, pylint, pytest-cov)
- JavaScript: 85% (tools: eslint, jscpd, nyc)
- Java: 90% (tools: PMD, JaCoCo, CheckStyle)
- Rust: 80% (tools: cargo-geiger, clippy, skip OO smells)
- **Overall**: 85% transferable ✅

**Universal Components** (13/16, 81%):
- SQALE formulas (100%)
- Prioritization matrix (100%)
- Paydown roadmap (100%)
- Code smell taxonomy (90%, OO smells excluded)
- Tracking approach (95%)
- Prevention practices (85%)

---

## Common Anti-Patterns

❌ **Measurement without action**: Calculating debt but not creating paydown plan
❌ **Strategic-only focus**: Skipping quick wins, tackling only big refactoring (low momentum)
❌ **No prevention**: Paying down debt without gates (debt re-accumulates)
❌ **Subjective prioritization**: "This code is bad" without quantified impact
❌ **Tool-free assessment**: Manual review instead of automated metrics (4.5x slower)
❌ **No tracking**: Point-in-time snapshot instead of continuous monitoring (reactive)

---

## Templates and Examples

### Templates
- [SQALE Index Report Template](templates/sqale-index-report-template.md) - Standard debt measurement report
- [Code Smell Categorization Template](templates/code-smell-categorization-template.md) - Map metrics to smells
- [Remediation Cost Breakdown Template](templates/remediation-cost-breakdown-template.md) - Estimate paydown effort
- [Transfer Guide Template](templates/transfer-guide-template.md) - Adapt methodology to new language

### Examples
- [SQALE Calculation Walkthrough](examples/sqale-calculation-example.md) - Step-by-step meta-cc example
- [Value-Effort Prioritization](examples/value-effort-matrix-example.md) - Prioritization matrix with real debt items
- [Phased Paydown Roadmap](examples/paydown-roadmap-example.md) - 4-phase plan with TD ratio improvements

---

## Related Skills

**Parent framework**:
- [methodology-bootstrapping](../methodology-bootstrapping/SKILL.md) - Core OCA cycle

**Complementary domains**:
- [testing-strategy](../testing-strategy/SKILL.md) - Coverage debt reduction
- [ci-cd-optimization](../ci-cd-optimization/SKILL.md) - Prevention gates
- [cross-cutting-concerns](../cross-cutting-concerns/SKILL.md) - Architectural debt patterns

---

## References

**Core methodology**:
- [SQALE Methodology](reference/sqale-methodology.md) - Complete SQALE guide
- [Code Smell Taxonomy](reference/code-smell-taxonomy.md) - SQALE categories with examples
- [Prioritization Framework](reference/prioritization-framework.md) - Value-effort matrix guide
- [Transfer Guide](reference/transfer-guide.md) - Language-specific adaptations

**Quick guides**:
- [15-Minute SQALE Analysis](reference/quick-sqale-analysis.md) - Fast debt measurement
- [Remediation Cost Estimation](reference/remediation-cost-guide.md) - Effort calculation

---

**Status**: ✅ Production-ready | Validated in meta-cc | 4.5x speedup | 85% transferable