🔧 Tech Debt Reducer

Systematic approach to identifying, prioritizing, and eliminating technical debt while improving code quality and performance.

Quick Reference

Task	Command/Action
Analyze complexity	Run scripts/analyze-complexity.ts
Find unused code	Run scripts/find-unused.ts
Detect code smells	Run scripts/detect-smells.ts
Generate debt report	Run scripts/debt-report.ts
Prioritize debt items	Follow "Prioritization Matrix" section

Core Methodology

Phase 1: Assessment (ALWAYS FIRST)

Before any refactoring, assess the current state:

## 📊 Tech Debt Assessment

### Codebase Metrics
- **Total Files**: [count]
- **Lines of Code**: [count]
- **Average Complexity**: [score]
- **Test Coverage**: [percentage]
- **Dependency Age**: [stats]

### Identified Issues
| Category | Count | Severity | Effort |
|----------|-------|----------|--------|
| Code Smells | X | High/Med/Low | S/M/L |
| Unused Code | X | Low | S |
| Complex Functions | X | Med | M |
| Outdated Deps | X | High | M |
| Missing Types | X | Med | S |

Phase 2: Categorization

Classify debt into categories:

Category	Description	Examples
Architecture	Structural issues	Circular deps, wrong abstractions
Code Quality	Maintainability issues	Long functions, duplicate code
Performance	Speed/memory issues	N+1 queries, memory leaks
Security	Vulnerability issues	Outdated deps, exposed secrets
Testing	Coverage gaps	Missing tests, flaky tests
Documentation	Knowledge gaps	Missing docs, outdated comments

Phase 3: Prioritization Matrix

Use the Impact vs Effort matrix:

High Impact │  Quick Wins    │  Strategic
            │  (Do First)    │  (Plan Carefully)
────────────┼────────────────┼─────────────────
Low Impact  │  Fill-ins      │  Avoid
            │  (If Time)     │  (Not Worth It)
            └────────────────┴─────────────────
              Low Effort       High Effort

Priority Formula: Score = (Impact × Risk) / Effort

Phase 4: Refactoring Patterns

See references/REFACTORING_PATTERNS.md for detailed patterns.

Safe Refactoring Workflow

1. ✅ Ensure tests exist (or write them first)
2. 📸 Create snapshot/checkpoint (git commit)
3. 🔧 Apply ONE refactoring at a time
4. 🧪 Run tests after each change
5. 📝 Commit with descriptive message
6. 🔄 Repeat

Code Smell Detection

Common Smells and Fixes

Smell	Detection	Fix
Long Function	>50 lines	Extract methods
Large Class	>300 lines	Split into smaller classes
Long Parameter List	>4 params	Use parameter object
Duplicate Code	Similar blocks	Extract common function
Dead Code	Unreachable code	Remove safely
Magic Numbers	Hardcoded values	Extract constants
God Object	Does too much	Single responsibility
Feature Envy	Uses other class data	Move method

TypeScript-Specific Smells

Smell	Example	Fix
any abuse	data: any	Proper types
Missing null checks	obj.prop	Optional chaining ?.
Type assertions	as Type	Type guards
Implicit any	No param types	Explicit types
No return types	Functions without	Add return types

Performance Optimization

Quick Wins

// ❌ Bad: Multiple re-renders
const items = data.filter(x => x.active).map(x => x.name);

// ✅ Good: Single pass with reduce
const items = data.reduce((acc, x) => {
  if (x.active) acc.push(x.name);
  return acc;
}, []);

// ❌ Bad: Creating functions in render
<Button onClick={() => handleClick(id)} />

// ✅ Good: useCallback or handler
const handleButtonClick = useCallback(() => handleClick(id), [id]);

// ❌ Bad: Missing memoization
const expensiveValue = computeExpensive(data);

// ✅ Good: useMemo for expensive computations
const expensiveValue = useMemo(() => computeExpensive(data), [data]);

Database Query Optimization

// ❌ Bad: N+1 Query
const users = await prisma.user.findMany();
for (const user of users) {
  const posts = await prisma.post.findMany({ where: { userId: user.id } });
}

// ✅ Good: Include related data
const users = await prisma.user.findMany({
  include: { posts: true }
});

// ✅ Better: Select only needed fields
const users = await prisma.user.findMany({
  select: { id: true, name: true, posts: { select: { title: true } } }
});

Dependency Management

Update Strategy

1. Check outdated: npm outdated
2. Review changelogs for breaking changes
3. Update in order: patch → minor → major
4. Test after each major update

Cleanup Unused Dependencies

# Find unused dependencies
npx depcheck

# Analyze bundle size
npx webpack-bundle-analyzer

# Check for duplicates
npm dedupe

Output Template

After completing debt reduction work:

## 🔧 Tech Debt Report

### 📊 Before/After Metrics
| Metric | Before | After | Change |
|--------|--------|-------|--------|
| Complexity | X | Y | -Z% |
| Lines of Code | X | Y | -Z% |
| Test Coverage | X% | Y% | +Z% |
| Bundle Size | X KB | Y KB | -Z% |

### ✅ Changes Made
1. [Description of change 1]
2. [Description of change 2]

### 🧪 Tests
- [ ] All existing tests pass
- [ ] New tests added for refactored code
- [ ] No regressions detected

### 📝 Follow-up Items
- [ ] Item that needs future attention

Safety Guidelines

• ❌ NEVER refactor without tests
• ❌ NEVER make multiple unrelated changes in one commit
• ❌ NEVER refactor and add features simultaneously
• ✅ ALWAYS commit working state before refactoring
• ✅ ALWAYS run tests after each change
• ✅ ALWAYS preserve external behavior

Escalation Criteria

Stop and reassess if:

• Tests start failing unexpectedly
• Refactoring scope grows beyond initial estimate
• Performance degrades after optimization
• Breaking changes affect public API