Tech Debt Tracker#

Systematically identify, categorize, and prioritize technical debt across a codebase. Analyzes TODO comments, complexity hotspots, stale dependencies, test coverage gaps, code duplication, and architectural debt. Produces actionable debt inventory with estimated effort and business impact.

Usage#

text

"Scan this codebase for tech debt"
"Prioritize our technical debt backlog"
"Find the highest-risk areas in our code"
"Generate a tech debt report for the team"

How It Works#

1. TODO/FIXME/HACK Mining#

bash

# Find all debt markers
grep -rn "TODO\|FIXME\|HACK\|XXX\|WORKAROUND\|TEMP\|DEPRECATED" src/ --include="*.{ts,js,py,rb,go,java,rs}" | head -50
# Age analysis — when were they added?
for match in $(grep -rln "TODO\|FIXME" src/); do
  oldest=$(git log --format=%ci --diff-filter=A -- "$match" | tail -1)
  count=$(grep -c "TODO\|FIXME" "$match")
  echo "$match: $count markers, file created: $oldest"
done

Categorize each marker:

• Deferred bugs: FIXME, known issues, edge cases
• Shortcuts: HACK, WORKAROUND, temporary code
• Missing features: TODO for planned work
• Deprecated code: DEPRECATED markers, sunset dates

2. Complexity Hotspots#

Identify files with highest change frequency AND highest complexity:

bash

# Most changed files (git churn)
git log --format=format: --name-only --since="6 months ago" | sort | uniq -c | sort -rn | head -20
# Largest files (often correlate with complexity)
find src/ -name "*.ts" -exec wc -l {} + | sort -rn | head -20

High churn + high complexity = highest debt risk. These files change often and are hard to modify safely.

3. Dependency Analysis#

• Outdated packages: Dependencies behind 2+ major versions
• Deprecated packages: Using packages with known replacements
• Security vulnerabilities: Unpatched CVEs in dependencies
• Abandoned packages: No commits in 12+ months
• Heavy dependencies: Large packages used for small features

4. Test Coverage Gaps#

• Files with zero test coverage but high change frequency
• Critical paths (auth, payments, data mutations) without integration tests
• Tests that don't assert behavior (snapshot-only, no real assertions)
• Flaky tests that are skipped or disabled

5. Code Duplication#

• Significant duplicated blocks (>10 lines)
• Similar functions that should be extracted
• Copy-paste patterns across modules
• Utility functions reimplemented in multiple places

6. Architectural Debt#

• Circular dependencies between modules
• God classes/files (>500 lines of logic)
• Tight coupling between layers
• Missing abstractions (direct DB calls in controllers)
• Dead code (unreachable functions, unused exports)
• Inconsistent patterns (some services use repos, some use raw queries)

7. Debt Prioritization#

Score each item on:

• Impact: How much does this slow down development? (1-5)
• Risk: What breaks if we don't fix it? (1-5)
• Effort: How long to fix? (hours/days/weeks)
• Priority: Impact × Risk / Effort

Output#

text

## Tech Debt Report

**Codebase:** 45K LOC across 312 files
**Scan date:** 2026-04-30
**Total debt items:** 87

### Debt Summary
| Category | Count | High Priority |
|----------|-------|---------------|
| TODO/FIXME markers | 34 | 8 |
| Complexity hotspots | 12 | 5 |
| Outdated dependencies | 18 | 3 |
| Test coverage gaps | 15 | 6 |
| Code duplication | 8 | 2 |

### 🔴 Top 5 Priority Items

1. **auth/session.ts** — 847 lines, 23 TODOs, changed 45 times in 6 months
   Impact: 5 | Risk: 5 | Effort: 3 days
   → Split into auth, session, and token modules

2. **Missing payment error handling** — FIXME on line 234
   Added 8 months ago, payment failures silently succeed
   Impact: 5 | Risk: 5 | Effort: 4 hours
   → Add proper error propagation and retry logic

3. **express@4.18 → 5.x migration** — 2 major versions behind
   Breaking changes in error handling middleware
   Impact: 3 | Risk: 4 | Effort: 2 days
   → Upgrade with middleware compatibility testing

4. **Zero test coverage on billing module** — 12 files, 2.3K LOC
   Changed 18 times in 6 months, no tests
   Impact: 4 | Risk: 5 | Effort: 1 week
   → Add integration tests for payment flows

5. **Duplicate user validation** — same logic in 4 controllers
   Impact: 3 | Risk: 2 | Effort: 2 hours
   → Extract to shared middleware

### 📊 Debt Trends
- New TODOs this month: 8 added, 3 resolved (net +5)
- Average TODO age: 4.2 months
- Oldest unresolved: 14 months (data-export.ts:67)
- Debt velocity: increasing (+2.3 items/month)

### 💡 Recommended Sprint Allocation
- Bug fixes: 60% of sprint
- Debt reduction: 20% of sprint (pick top 2-3 items)
- New features: 20% of sprint