tech-debt-tracker

Trigger phrases

Phrases that activate this skill when typed to Claude Code:

• scan for tech debt
• audit technical debt
• track tech debt trends

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 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, part of his Engineering POWERFUL Tier.

License: MIT.

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