techdebt-scan

Technical Debt Scanner

Find and safely fix technical debt using TDD approach.

Order: SCAN -> TEST CASES -> REFACTOR -> VERIFY (do NOT skip steps!)

Phase 1: SCAN

Run scan scripts:

bash .cursor/skills/techdebt-scan/scripts/scan-large-files.sh
bash .cursor/skills/techdebt-scan/scripts/find-todos.sh

Then check for:

• Files > 300 lines (routes, services, components > 200 lines)
• Duplicated code patterns (grep for identical blocks > 5 lines)
• Functions > 50 lines
• Deep nesting (> 3 levels)
• Files with > 10 exports
• Magic numbers/strings

Scan Results Template

## TECHDEBT SCAN RESULTS — [date]

### Oversized Files
| File | Lines | Limit | Severity |
|------|-------|-------|----------|
| <path> | X | Y | HIGH/MED |

### Duplicate Code
| Pattern | File 1 | File 2 | Lines | Severity |
|---------|--------|--------|-------|----------|
| <desc> | <path> | <path> | X | HIGH/MED |

### Code Smells
| Type | Location | Description | Severity |
|------|----------|-------------|----------|
| Long function | <path>:<line> | X lines | MED |

### Exceptions (NOT violations)
| File | Exception Type | Reason |
|------|---------------|--------|
| <path> | High Cohesion Monolith | <reason> |

High Cohesion Monolith criteria:

• Single business responsibility (not a god-object)
• High method cohesion -- methods share common state
• Splitting requires full test coverage for safety

Phase 2: PRIORITIZE

Phase 3: TEST CASES (MANDATORY before refactoring)

Write tests BEFORE any code changes. For each selected issue:

1. Create test cases table
2. Write failing tests
3. Verify tests FAIL (code not changed yet)

Phase 4: REFACTOR

1. Small steps -- one file at a time
2. Run tests after EACH change
3. Commit after each green test

Phase 5: VERIFY

## TECHDEBT FIX VERIFICATION
| ID | Description | Tests Written | Tests Passing | Status |
|----|-------------|---------------|---------------|--------|
| D1 | <desc> | X | X | OK |

- [ ] `npm run build` -- success
- [ ] `npm run lint` -- 0 errors
- [ ] `npm test` -- all passing

FORBIDDEN

• Refactoring without SCAN first
• Refactoring without TEST CASES
• Writing tests AFTER refactoring
• "Build passed = everything works"