Tech Debt Tracker

---
name: tech-debt-tracker
description: Use when cataloging or prioritizing tech debt across a codebase. Triggers on "tech debt", "code health", "paydown plan", "refactor backlog".
---

# Tech Debt Tracker

Tech debt is real and bounded — most teams underestimate it AND overestimate the value of paying it down. The discipline is: name it, size it, schedule it, kill it. Not "we should rewrite this someday."

## Required inputs

1. **Codebase + scope** — full repo, or specific service
2. **Known pain points** — the things that already hurt (slow tests, fragile code, missing tests)
3. **Team capacity** — how much bandwidth realistically goes to debt vs. features
4. **Recent incidents** — bugs / outages that point at specific debt

## Output

### Debt catalog
Each item:
- **Name** (specific — "rate-limiting missing on public API" not "API is bad")
- **Location** (files, services)
- **Why it's debt** (the cost we're paying — slower dev, bugs, outage risk, recruiting friction)
- **Estimated fix cost** (eng-weeks, low confidence is fine)
- **Cost of not fixing in 12 months** (specific, not "things will break")
- **Risk if it explodes** (Low / Medium / High — with the scenario)

### Ranking
Sort by (cost-of-not-fixing / cost-of-fixing). Items at the top: fix soon. Items at the bottom: defer or accept permanently.

### Categories
- **Acute** — actively causing incidents or churn. Fix now.
- **Compounding** — getting worse over time, not crisis yet. Fix in next quarter.
- **Latent** — would bite if X happens (10x scale, regulatory change, key person leaves). Fix when X gets closer.
- **Cosmetic** — annoying but doesn't actually cost much. Accept or defer permanently.

### Cadence proposal
- 15-25% of eng bandwidth to debt is sustainable
- Bigger sprints (1-2 weeks dedicated) are better than always-on small debt work, in most cases
- Track total debt count + age trend, not just velocity

### Anti-debt-list
The items the team agrees NOT to call debt:
- Things that are intentionally simple
- Things that work fine and aren't blocking anything
- Things one engineer finds aesthetically displeasing

Naming what's NOT debt prevents the catalog from becoming a venting board.

## What this skill won't do

- Pick which items the leadership team should prioritize (that's a meeting, not a script)
- Rewrite-everything projects (start with smaller fixes, build trust, scale)
- Defend specific architectural choices (different skill — architecture review)

## When the catalog is useful

- Before planning a quarter — informs capacity decisions
- When new engineer joins — orients them to the landscape
- When leadership asks "are we shipping fast" — concrete answer with numbers, not vibes
- When pitching debt-paydown budget — armed with cost-of-inaction estimates