santosomar/technical-debt-analyzer

Technical Debt Analyzer

Technical debt is a cost metaphor: structure you'd build differently today, paid for in slower future changes. The analysis question is not "where is the bad code?" — it's "where does the bad code cost the most?"

The cost equation

debt_cost(file) = interest_rate(file) × principal(file)

• Principal = how much work to fix the structure. Size of the refactor.
• Interest rate = how often you pay. Change frequency.

A terrible file nobody touches has high principal, zero interest → zero cost. Pay down debt where the product is high.

Signals — gathering the data

| Signal | How to measure | What it tells you | | ------------------------- | ------------------------------------------------------------------ | ------------------------------------ | | Change frequency | git log --since=6.months --format= --name-only \| sort \| uniq -c | Interest rate | | Churn (lines changed) | git log --since=6.months --numstat | Interest rate (finer-grained) | | Complexity | Cyclomatic complexity, nesting depth, LOC per function | Principal | | Smell density | → code-smell-detector findings per KLOC | Principal | | Coupling | Fan-in (how many files import this) | Blast radius — changes here break many things | | Bug concentration | git log --grep=fix --format= --name-only \| sort \| uniq -c | Where bugs actually happen — empirical interest | | Test coverage | Coverage report | Cost of safe refactor — low coverage = high risk | | Author count | git log --format=%an -- <file> \| sort -u \| wc -l | Knowledge fragmentation — 8 authors, nobody owns it | | TODO/FIXME/HACK | rg 'TODO\|FIXME\|HACK\|XXX' | Self-reported debt — the team already knows |

The hotspot map

Plot files on two axes: complexity (y) vs change frequency (x).

              │  (cold+complex)         (HOT+complex) ← pay down here
  complexity  │  low priority            HIGH PRIORITY
              │
              │  (cold+simple)          (hot+simple)
              │  ignore                  healthy — leave alone
              └──────────────────────────────────
                        change frequency

The upper-right quadrant is where every sprint loses time. That's the paydown target.

Worked example

Input: Mid-size service, ~200 files. After gathering signals:

| File | Commits (6mo) | Cyclomatic | Bugs (6mo) | Coverage | Authors | | ----------------------- | ------------- | ---------- | ---------- | -------- | ------- | | billing/invoice.py | 34 | 58 | 7 | 31% | 6 | | api/handlers.py | 41 | 22 | 2 | 78% | 4 | | legacy/xml_export.py | 2 | 91 | 0 | 0% | 1 | | utils/date.py | 19 | 8 | 1 | 95% | 3 |

Analysis:

• billing/invoice.py: Top priority. High churn + high complexity + high bugs + low coverage = you're paying maximum interest on maximum principal, and you can't safely refactor it. Step 1 is coverage.
• api/handlers.py: High churn but moderate complexity and good coverage. This is healthy hot code — it changes because the product changes. Leave it.
• legacy/xml_export.py: Off-the-charts complexity, zero coverage — but 2 commits in 6 months and zero bugs. It's frozen. Principal is huge but interest is zero. Don't touch.
• utils/date.py: Boring. Fine.

Output:

Debt hotspots

1. billing/invoice.py — 34 commits, cyclomatic 58, 7 bugs, 31% coverage. Every billing change takes 2× longer than it should. Seven bugs in six months is the highest concentration in the codebase. Paydown plan: (a) add characterization tests to reach 70% coverage — ~3 days; (b) extract InvoiceCalculator from the 200-line compute() — ~2 days; (c) split Invoice god class by state (draft vs. issued) — ~1 week. Step (a) is a prerequisite; do not skip.

Explicitly not paying down

• legacy/xml_export.py — complexity 91, but 2 commits in 6 months and zero bugs. Stable. Touching it is risk without reward.

Debt you can't measure from the code

Some debt is in people's heads, not in the AST:

• Knowledge debt: One person understands the payment flow; they're leaving. The code might be clean, but the cost of change just went up 10×.
• Decision debt: The team chose Mongo in 2018; the access patterns are now relational. The code is fine; the choice isn't.
• Dependency debt: Pinned to a library version that's EOL. The code is fine until the CVE drops.

Ask about these. They don't show up in git log.

Do not

• Do not rank by complexity alone. Complex frozen code is free. Simple hot code is also free. Only the product matters.
• Do not report a debt score without a paydown plan. "This file scores 847 debt points" is useless. "Refactoring this file will take ~1 week and will stop costing you ~2 hours per billing change" is actionable.
• Do not recommend rewriting. Rewrites are how debt doubles. Recommend incremental paydown with tests as the safety net.
• Do not ignore low-coverage hotspots. They're the most expensive and the hardest to fix safely — which is exactly why they stay expensive. Break the cycle: coverage first.

Output format

## Hotspots (pay down)
<N>. <file>  — <churn> commits, complexity <N>, <N> bugs, <N>% coverage
    Interest: <what this costs per sprint — be concrete>
    Principal: <what the refactor is, roughly how long>
    Prerequisite: <coverage? knowledge? — anything blocking safe refactor>

## Explicitly deferred (high principal, low interest)
- <file> — <why it's safe to ignore>

## Non-code debt (from asking, not measuring)
- <knowledge / decision / dependency debt>