# tech-debt-tracker

> A Claude Code skill that scans a codebase for technical debt indicators, prioritizes findings by production impact, and produces trend dashboards so refactoring decisions can be informed by data instead of vibes.

**Use case**: Identify and prioritize tech debt with data, not gut feel

**Canonical URL**: https://agentcookbooks.com/skills/tech-debt-tracker/

**Topics**: claude-code, skills, refactoring, tech-debt, code-quality

**Trigger phrases**: "scan for tech debt", "audit technical debt", "track tech debt trends"

**Source**: [Alireza Rezvani](https://github.com/alirezarezvani/claude-skills/tree/main/engineering/tech-debt-tracker)

**License**: MIT

---

## What it does

`tech-debt-tracker` scans a codebase for the patterns that usually signal tech debt — sprawling files, deep nesting, repeated TODOs, dead code, dependency tangles, low test coverage in change-frequent areas — and produces a prioritized findings list ordered by production impact.

The output isn't a wall of complaints. It's a ranked list: what's actually bleeding, what's painful but stable, what's noise. Run periodically, the skill surfaces a trend ("debt density in the auth module rose 22% over four sprints") so you can decide where to spend a refactoring sprint with evidence instead of guesses.

## When to use it

- Planning a refactoring sprint and you want a data-grounded target list
- Onboarding into a codebase you didn't write — get a quick map of the rough terrain
- Pre-RFC investigation: before proposing an architectural change, scan to back up the case
- Quarterly debt review where you want comparable numbers, not anecdotes

When *not* to reach for it:

- Greenfield projects with no debt yet — you'll generate noise
- Tiny codebases where you already know exactly where the debt lives
- When the answer is obvious — sometimes you don't need a ranking, you need to ship the fix

## Install

From the [claude-skills repo](https://github.com/alirezarezvani/claude-skills) under `engineering/tech-debt-tracker/`. Install per the documented path.

## What a session looks like

1. **You point the skill at the repo** (or a subset — a specific module or service).
2. **It scans for debt indicators** — file size, nesting, complexity hotspots, TODO/FIXME density, dependency cycles, change frequency × code quality intersections.
3. **It prioritizes findings** by *production impact*: a tangled module that's touched every sprint outranks a tangled module nobody touches.
4. **It produces a structured report** with the top items, the patterns under each, and the proposed refactoring direction. Run again later to see trends.

The discipline that makes it work: prioritization by *impact*, not by *severity*. A 1500-line file in cold code is technically debt but might never matter; a 200-line file in change-heavy code is the urgent one.

## Receipts

**Where it works well:**
- Surfaces the change-frequency × complexity intersection that matters most for refactoring ROI
- Trend tracking across runs gives you defensible "things are getting worse / better" data
- The prioritized output is short enough to act on (top 5–10 items, not 200)

**Where it backfires:**
- The scan can flag legitimate domain complexity as debt; review findings, don't auto-fix
- Some "debt" patterns are organizational, not code-shaped — the skill won't catch those
- Running on a monorepo without scoping produces noise; scope to a service or module

**Pattern that works:** run quarterly per service or per module, scoped narrowly. Track trend deltas across runs. Bring the report to refactoring planning instead of relying on whoever-shouts-loudest.

## Source and attribution

From [Alireza Rezvani's claude-skills repository](https://github.com/alirezarezvani/claude-skills/tree/main/engineering/tech-debt-tracker), part of his Engineering POWERFUL Tier.

License: MIT.

For the canonical install and supported language coverage, defer to the source repo.