Tech Debt Hunter Command

Command

/tech-debt

Description

Systematically scans your codebase for technical debt and organizes findings into an actionable, prioritized backlog. Goes beyond simple TODO scanning to identify code complexity, duplication, outdated patterns, missing tests, and dependency risks.

Behavior

Arguments

• $ARGUMENTS -- Optional scope (e.g., src/services/ or --category=testing)

Scan Categories

1. Code Markers

Copy
# Find TODO, FIXME, HACK, XXX, TEMP comments
grep -rn 'TODO\|FIXME\|HACK\|XXX\|TEMP\|WORKAROUND' src/ --include='*.ts' --include='*.tsx'

2. Code Complexity

• Functions over 50 lines
• Files over 500 lines
• Deeply nested code (4+ levels of indentation)
• Functions with many parameters (5+)
• Cyclomatic complexity hotspots

3. Duplication

• Repeated code blocks across files
• Copy-pasted utility functions
• Similar components that should be abstracted

4. Testing Gaps

• Source files with no corresponding test file
• Test files with minimal assertions
• Missing edge case coverage
• No integration tests for critical paths

5. Dependency Health

Copy
# Outdated dependencies
npm outdated 2>/dev/null
# Vulnerability check
npm audit --production 2>/dev/null

6. Outdated Patterns

• Deprecated API usage
• Legacy framework patterns (class components, callbacks)
• Inconsistent code style across the project

Output Format

Copy
## Tech Debt Report

**Scanned**: 234 files in src/
**Total Items**: 47

### Summary by Category
| Category | Count | Effort (total) |
|----------|-------|---------|
| Code Markers (TODO/FIXME) | 18 | 3 days |
| Complexity Hotspots | 8 | 5 days |
| Testing Gaps | 12 | 4 days |
| Outdated Dependencies | 5 | 1 day |
| Code Duplication | 4 | 2 days |

### Priority Backlog

#### P1: High Impact, Low Effort (Do First)
| Item | File | Category | Effort |
|------|------|----------|--------|
| FIXME: Race condition in payment processing | src/services/payment.ts:89 | Bug Risk | 2h |
| Missing auth check on admin endpoint | src/routes/admin.ts:23 | Security | 1h |
| No tests for order cancellation flow | src/services/orders.ts | Testing | 3h |

#### P2: High Impact, High Effort (Plan Next Sprint)
| Item | File | Category | Effort |
|------|------|----------|--------|
| UserService is 800 lines, needs splitting | src/services/userService.ts | Complexity | 1d |
| 3 duplicate validation functions | src/utils/, src/services/ | Duplication | 4h |

#### P3: Low Impact (Backlog)
| Item | File | Category | Effort |
|------|------|----------|--------|
| TODO: Add pagination to user list | src/routes/users.ts:45 | Feature Gap | 2h |
| moment.js -> date-fns migration | package.json | Modernization | 3h |

### Recommendations
1. Start with P1 items -- they have the best ROI
2. Allocate 20% of sprint capacity to tech debt
3. Address security items immediately regardless of priority

Examples

Copy
# Full codebase scan
/tech-debt

# Scan specific directory
/tech-debt src/services/

# Focus on testing gaps only
/tech-debt --category=testing

# Focus on security-related debt
/tech-debt --category=security