| name | technical-debt-analyzer |
| description | Analyzes a codebase to quantify and locate technical debt — where it lives, what it costs, and what order to pay it down in. Use when planning a refactoring sprint, when justifying engineering time to stakeholders, when the user asks where the codebase hurts most, or when onboarding to a legacy system. |
| license | Apache-2.0 |
| metadata | {"category":"code-quality","suite":"general-secure-coding-agent-skills","version":"0.3.0","related":"code-smell-detector, code-refactoring-assistant, dead-code-eliminator"} |
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
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>
