Tech Debt

Overview

Technical debt is borrowed time — the gap between the code you have and the code you need. Left unmanaged, it compounds interest: every new feature costs more, every bug takes longer to fix.

Core principle: Not all debt is equal. Pay down debt that blocks you, not debt that merely annoys you.

Iron Law:

MEASURE DEBT BEFORE PAYING IT. PRIORITIZE BY IMPACT, NOT BY DISCOMFORT.

When to Use

• Sprint planning (decide which debt to pay down)
• Before major feature work (assess what debt will slow you down)
• After incidents (identify debt that contributed)
• Quarterly tech health reviews
• Before refactoring (use the refactoring skill after this one)

Types of Technical Debt

The Assessment Process

Phase 1: Discover

Automated discovery:

# Code complexity
npx ts-complexity src/ --threshold 10

# Duplicate code
npx jscpd src/ --min-lines 5 --reporters console

# Test coverage gaps
npx jest --coverage

# Dependency age and CVEs
npm outdated
npm audit

# TODO/FIXME/HACK markers
grep -rn "TODO\|FIXME\|HACK\|XXX\|TEMP\|WORKAROUND" \
  --include="*.ts" --include="*.js" src/ | wc -l

Manual discovery checklist:

Architecture smells:
- [ ] Classes > 300 lines (God class)
- [ ] Functions > 30 lines (God function)
- [ ] Files with > 10 imports (high coupling)
- [ ] Circular dependencies
- [ ] Global mutable state

Code quality smells:
- [ ] Duplicate code blocks (> 5 lines, 2+ occurrences)
- [ ] Magic numbers/strings without constants
- [ ] Deep nesting (> 3 levels)
- [ ] Long parameter lists (> 4 params)
- [ ] Boolean traps (function(true, false, false))

Test smells:
- [ ] Test coverage < 80%
- [ ] Tests that always pass (no assertions)
- [ ] Tests that mock everything
- [ ] No integration tests
- [ ] Flaky tests

Phase 2: Catalog

Create a tech debt register:

## Tech Debt Register — [Date]

| ID | Type | Description | File | Discovered | Owner |
|----|------|-------------|------|------------|-------|
| TD-001 | Architecture | McpService is a God class (450 lines) | mcp.service.ts | 2024-01-15 | — |
| TD-002 | Test | RulesService has 45% coverage | rules.service.ts | 2024-01-15 | — |
| TD-003 | Dependency | NestJS 9 → 10 migration pending | package.json | 2024-01-15 | — |
| TD-004 | Code quality | searchRules logic duplicated 3 times | *.service.ts | 2024-01-15 | — |

Phase 3: Prioritize

Priority formula:

Priority Score = (Velocity Impact × Bug Risk) / Effort

Scale: 1-5 for each factor
- Velocity Impact: How much does this slow down development?
- Bug Risk: How likely is this to cause bugs?
- Effort: How hard is this to fix?

Prioritization matrix:

| ID | Description | Velocity | Bug Risk | Effort | Score |
|----|-------------|----------|----------|--------|-------|
| TD-001 | God class McpService | 4 | 3 | 4 | (4×3)/4 = 3.0 |
| TD-002 | Low test coverage | 3 | 5 | 2 | (3×5)/2 = 7.5 ← Fix first |
| TD-003 | NestJS upgrade | 2 | 3 | 3 | (2×3)/3 = 2.0 |
| TD-004 | Duplicate logic | 3 | 3 | 1 | (3×3)/1 = 9.0 ← Fix first |

Priority tiers:

• Score ≥ 7: Fix this sprint (blocks progress)
• Score 4-7: Fix this quarter (accumulating interest)
• Score < 4: Backlog (low ROI)

Phase 4: Plan Resolution

For each high-priority item, create a paydown plan:

## Paydown Plan: TD-004 (Duplicate searchRules logic)

**Goal:** Extract shared search logic into reusable utility

**Approach:** Refactoring skill (not a rewrite)

**Steps:**
1. Write tests covering all three duplicate sites (2h)
2. Extract to `src/shared/search.utils.ts` (1h)
3. Replace all three call sites (1h)
4. Verify tests pass (30m)

**Risk:** Low — covered by tests before and after
**Estimate:** 4.5h
**Assigned to:** —

**Definition of Done:**
- [ ] Tests cover all search scenarios
- [ ] Single implementation in search.utils.ts
- [ ] All three call sites use shared utility
- [ ] Coverage increased to > 90% for search logic

Phase 5: Track Progress

Update the debt register as items are resolved:

| ID | Status | Resolution | Date |
|----|--------|------------|------|
| TD-004 | ✅ Done | Extracted to search.utils.ts | 2024-01-20 |
| TD-002 | 🔄 In Progress | Coverage at 78%, target 90% | — |
| TD-001 | 📋 Planned | Sprint 5 | — |
| TD-003 | 🚫 Deferred | Low score, Q2 | — |

Debt Prevention

Good practices that prevent debt accumulation:

Definition of Done (add these):
- [ ] New code has > 80% test coverage
- [ ] No functions > 30 lines
- [ ] No TODO/FIXME left in merged code
- [ ] Dependencies not introducing CVEs
- [ ] Architecture review for files > 200 lines

The Boy Scout Rule: Leave code cleaner than you found it.

• Fix ONE small thing whenever you touch a file
• 10 minutes per PR on adjacent debt
• Over time: debt decreases without dedicated sprints

Talking About Debt

With product managers:

❌ "We need a refactoring sprint"
✅ "The authentication module is slowing every login feature
   by 3x. A 2-day investment now saves 6 days in the next
   quarter. Here's the ROI breakdown."

In sprint planning:

Rule of thumb:
- 20% capacity on debt paydown (sustainable)
- 0% = debt accumulates, velocity declines
- 50%+ = not enough new value

Quick Reference

Red Flags — STOP