| name | tech-debt |
| description | Technical debt identification and tracking. Activated when the user says "tech debt", "technical debt", "cleanup backlog", "what needs fixing", "code health", "debt audit", "code quality scan", or wants to systematically find and prioritize tech debt. |
| allowed tools | Read, Write, Edit, Grep, Glob, Bash |
Tech Debt Tracker
Systematically identify, catalog, and prioritize technical debt.
Not opinions — evidence-based assessment from the codebase itself.
Rules
- Evidence over opinion — every debt item must reference specific files, lines, or metrics
- Quantify impact — estimate effort to fix and cost of NOT fixing
- Prioritize by risk — debt near active features > debt in dormant code
- Check history — use git log to find high-churn files (debt compounds where changes are frequent)
- Output to docs — write report to
docs/architecture/tech-debt-report-{date}.md
- Don't fix during audit — catalog first, fix later (separate concerns)
Debt Categories
1. Code quality debt
2. Dependency debt
3. Test debt
4. Architecture debt
5. Documentation debt
6. Infrastructure debt
Workflow
Phase 1: Automated scan
Run these commands and capture results:
grep -rn "TODO\|FIXME\|HACK\|XXX" src/ --include="*.[SPEC]" | wc -l
grep -rn "@ts-ignore\|@ts-expect-error\|# type: ignore\|nolint" src/ | wc -l
git log --since="3 months ago" --name-only --pretty=format: -- src/ | sort | uniq -c | sort -rn | head -10
find src/ -name "*.[SPEC]" -exec wc -l {} + | sort -rn | head -10
grep -rn "\.skip\|@skip\|xit\b\|xdescribe\b\|@pytest.mark.skip" src/ tests/ | wc -l
Phase 2: Manual assessment
For each finding from Phase 1:
- Is this actually debt? (Sometimes a TODO is tracked elsewhere, or a suppression is justified)
- What's the impact? (Blocks feature work? Causes bugs? Just ugly?)
- Where does it live? (Near active code or dormant?)
Phase 3: Prioritize
Score each debt item:
| Factor | High (3) | Medium (2) | Low (1) |
|---|
| Frequency | Near code changed weekly | Changed monthly | Rarely touched |
| Severity | Causes bugs or blocks features | Slows development | Cosmetic |
| Effort | < 1 hour to fix | 1 day to fix | > 1 week to fix |
Priority = (Frequency + Severity) × (1/Effort)
High frequency + high severity + low effort = fix first.
Phase 4: Report
Write docs/architecture/tech-debt-report-{date}.md:
# Tech Debt Report — {date}
## Summary
- Total items: {N}
- Critical (fix now): {N}
- Important (fix soon): {N}
- Minor (fix when nearby): {N}
## Critical items
### 1. [Title]
- **Location**: file:line
- **Category**: [code quality | dependency | test | architecture | docs | infra]
- **Impact**: [what happens if we don't fix it]
- **Effort**: [estimate]
- **Evidence**: [specific finding]
## Important items
...
## Minor items
...
## Metrics
- TODOs/FIXMEs: {N}
- Type suppressions: {N}
- Skipped tests: {N}
- Files > 500 lines: {N}
- Dependencies outdated: {N}
References
docs/architecture/ — past tech debt reports and ADRsdocs/specs/testing-strategy/ — coverage requirementsdocs/specs/observability/ — monitoring gaps- CLAUDE.md Gotchas — known issues
