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

"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

# 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:

# 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

## 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