How to Manage Technical Debt: Assessment, Prioritization, and Paydown

Technical debt isn’t a metaphor — it’s a measurable drag on velocity. Companies with high technical debt spend 33-50% of engineering time on rework, workarounds, and firefighting instead of new features.

Step 1: Classify Your Debt

Debt Taxonomy

Category	Examples	Impact	Effort to Fix
Code Debt	Duplicated logic, missing abstractions, god classes	Slower feature development	Medium
Architecture Debt	Monolith that should be services, wrong DB choice	System-wide limitations	High
Test Debt	No tests, flaky tests, untested edge cases	Deployments break production	Medium
Infrastructure Debt	Manual deployments, missing monitoring, no DR	Outages, slow recovery	Medium-High
Documentation Debt	No onboarding docs, outdated API specs	Slow onboarding, knowledge loss	Low
Dependency Debt	Outdated libraries, unsupported frameworks	Security vulnerabilities	Medium

Step 2: Quantify the Cost

2.1 Developer Survey Method

# Survey template (send to all engineers)
survey_questions = {
    "time_lost_weekly_hours": "How many hours per week do you lose to workarounds, slow tools, or code complexity?",
    "top_3_pain_points": "What are the top 3 areas in the codebase that slow you down?",
    "deployment_confidence": "On a scale of 1-10, how confident are you that a deployment won't break production?",
    "onboarding_time_weeks": "How many weeks does it take a new developer to contribute meaningfully?",
}

# Aggregate results
avg_time_lost = 6.3  # hours/week/developer
team_size = 15
fully_loaded_hourly = 85  # $/hour including benefits

weekly_debt_cost = avg_time_lost * team_size * fully_loaded_hourly
annual_debt_cost = weekly_debt_cost * 50  # ~50 working weeks

print(f"Weekly cost of tech debt: ${weekly_debt_cost:,.0f}")
print(f"Annual cost of tech debt: ${annual_debt_cost:,.0f}")
# Example output:
# Weekly cost: $8,033
# Annual cost: $401,625

2.2 Code Quality Metrics

# SonarQube analysis
sonar-scanner \
  -Dsonar.projectKey=myproject \
  -Dsonar.sources=./src \
  -Dsonar.host.url=http://sonarqube:9000

# Extract key metrics via API
curl -s "http://sonarqube:9000/api/measures/component?component=myproject&metricKeys=sqale_debt_ratio,code_smells,bugs,vulnerabilities,coverage" | jq '.component.measures'

Metric	Good	Warning	Critical
Code Smells	< 100	100-500	> 500
Test Coverage	> 80%	50-80%	< 50%
Duplication	< 3%	3-10%	> 10%
SQALE Rating	A	B-C	D-E
Dependency CVEs	0 critical	0 critical, < 5 high	Any critical

Step 3: Prioritize with the Impact-Effort Matrix

HIGH IMPACT
    │
    │  ┌─────────────┐    ┌─────────────┐
    │  │  QUICK WINS  │    │  STRATEGIC  │
    │  │  Do First    │    │  Plan & Do  │
    │  │ (Sprint 1-2) │    │ (Quarters)  │
    │  └─────────────┘    └─────────────┘
    │
    │  ┌─────────────┐    ┌─────────────┐
    │  │   FILLERS    │    │   AVOID     │
    │  │ When idle    │    │  Not worth  │
    │  │              │    │  the effort │
    │  └─────────────┘    └─────────────┘
    │
    └──────────────────────────────────── HIGH EFFORT

Scoring Template

debt_items = [
    {
        "name": "Migrate from jQuery to vanilla JS",
        "impact": 7,      # 1-10: How much does this slow us down?
        "effort": 8,      # 1-10: How much work to fix?
        "risk": 6,         # 1-10: What breaks if we don't fix it?
        "frequency": 9,    # 1-10: How often is this felt?
    },
    {
        "name": "Add unit tests to checkout module",
        "impact": 9,
        "effort": 4,
        "risk": 8,
        "frequency": 7,
    },
    {
        "name": "Refactor database connection pooling",
        "impact": 6,
        "effort": 3,
        "risk": 5,
        "frequency": 4,
    },
]

# Calculate priority score
for item in debt_items:
    item["priority"] = (
        item["impact"] * 0.3 +
        item["risk"] * 0.3 +
        item["frequency"] * 0.2 +
        (10 - item["effort"]) * 0.2  # Lower effort = higher priority
    )

# Sort by priority
for item in sorted(debt_items, key=lambda x: x["priority"], reverse=True):
    print(f"  [{item['priority']:.1f}] {item['name']}")

Step 4: Allocate Sprint Capacity

The 20% Rule

Reserve 20% of every sprint for technical debt paydown. This is non-negotiable.

Sprint Capacity	Feature Work	Debt Paydown	Maintenance
50 points	35 points (70%)	10 points (20%)	5 points (10%)

Tracking Progress

# Track debt reduction over time
sprint_data = [
    {"sprint": 1, "debt_items_resolved": 3, "new_debt_added": 1, "velocity_impact": "+2%"},
    {"sprint": 2, "debt_items_resolved": 4, "new_debt_added": 2, "velocity_impact": "+3%"},
    {"sprint": 3, "debt_items_resolved": 5, "new_debt_added": 1, "velocity_impact": "+5%"},
]

cumulative_resolved = sum(s["debt_items_resolved"] for s in sprint_data)
cumulative_added = sum(s["new_debt_added"] for s in sprint_data)
net_reduction = cumulative_resolved - cumulative_added
print(f"Net debt reduction: {net_reduction} items over {len(sprint_data)} sprints")

Step 5: Prevent New Debt

Quality Gates

# .github/workflows/quality.yml
name: Quality Gate
on: pull_request

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run Tests
        run: npm test -- --coverage

      - name: Check Coverage Threshold
        run: |
          COVERAGE=$(cat coverage/coverage-summary.json | jq '.total.lines.pct')
          if (( $(echo "$COVERAGE < 80" | bc -l) )); then
            echo "❌ Coverage $COVERAGE% below 80% threshold"
            exit 1
          fi

      - name: Lint Check
        run: npx eslint . --max-warnings 0

      - name: Complexity Check
        run: npx complexity-report --max-complexity 15 src/

Technical Debt Checklist

:::note[Source] This guide is derived from operational intelligence at Garnet Grid Consulting. For architecture audits, visit garnetgrid.com. :::