---
name: tech-debt-hunter
description: Scan codebase for technical debt, prioritize fixes, and auto-refactor low-risk debt. Keep codebase clean proactively.
---

# Tech Debt Hunter

Actively hunt and eliminate technical debt before it becomes a problem.

## Debt Categories

### 🔴 Critical Debt (Fix immediately)
```
- Security vulnerabilities
- Data integrity risks
- Performance bottlenecks causing outages
- Deprecated dependencies with known CVEs
```

### 🟡 High Debt (Fix this sprint)
```
- No test coverage on critical paths
- Hardcoded configurations
- Copy-pasted code blocks
- Missing error handling
- N+1 query problems
```

### 🟠 Medium Debt (Fix this month)
```
- Outdated dependencies (non-security)
- Inconsistent code style
- Missing documentation
- Complex functions (>50 lines)
- Deep nesting (>4 levels)
```

### 🟢 Low Debt (Backlog)
```
- Minor code smells
- Naming improvements
- Comment cleanup
- Unused imports
- TODO comments
```

## Auto-Detection Patterns

### Code Smells
```regex
# TODO/FIXME/HACK comments
(TODO|FIXME|HACK|XXX|TEMP):?

# Magic numbers
[^0-9][0-9]{3,}[^0-9]

# Long functions (detect by line count)
func.*\{[\s\S]{2000,}\}

# Deep nesting
\{\s*\{\s*\{\s*\{\s*\{
```

### Dependency Debt
```bash
# Outdated packages
npm outdated
go list -u -m all
pip list --outdated
```

### Test Debt
```bash
# Coverage gaps
go test -cover ./...
npm run test:coverage
```

## Debt Report Template

```
📊 TECH DEBT REPORT: [Project]
Scanned: [Date]

┌─────────────────────────────────────────────┐
│ Debt Summary                                │
├─────────────────────────────────────────────┤
│ 🔴 Critical: 2 items                        │
│ 🟡 High: 8 items                            │
│ 🟠 Medium: 15 items                         │
│ 🟢 Low: 23 items                            │
│                                             │
│ Debt Score: 6.5/10 (was 5.8 last month)    │
└─────────────────────────────────────────────┘

🔴 CRITICAL (Fix NOW):
1. [CVE-2024-XXXX] axios@0.21.0 vulnerable
   → Fix: npm update axios

2. SQL injection in /api/search
   → Fix: Use parameterized query

🟡 HIGH (Fix this sprint):
1. No tests for payment module (0% coverage)
   → Impact: Payment bugs undetected

2. Copy-pasted auth logic in 3 places
   → Fix: Extract to shared module

📈 Trend: Improving (+0.7 from last month)

🎯 Recommended Sprint Goals:
- [ ] Fix 2 critical issues (required)
- [ ] Fix 3 high issues
- [ ] Add tests for payment module
```

## Auto-Fix Rules

### Safe to Auto-Fix (Just do it):
```
- Update patch versions
- Remove unused imports
- Fix linting errors
- Sort imports
- Format code
- Remove console.logs
```

### Requires Review (Fix + report):
```
- Update minor versions
- Refactor duplicated code
- Simplify complex functions
- Add missing error handling
```

### Manual Only (Report + suggest):
```
- Major version updates
- Architecture changes
- Database schema changes
- API contract changes
```

## Integration

### On Every PR/Commit:
1. Scan changed files for new debt
2. Block if critical debt introduced
3. Warn on high debt
4. Track debt score over time

### Weekly Scan:
1. Full codebase scan
2. Generate debt report
3. Compare to last week
4. Auto-fix safe items
5. Create issues for manual items

## Debt Prevention Rules

```
Enforce in code review:
- No TODO without issue link
- No magic numbers
- No functions > 50 lines
- No files > 500 lines
- No copy-paste > 10 lines
- Test coverage > 70%
```