Technical Debt

Technical Debt Skill

Systematically identify, track, and resolve technical debt.

When to Use

• Scanning codebase for technical debt
• Categorizing and prioritizing debt items
• Creating debt tracking files
• Planning debt resolution sprints
• Measuring debt trends over time

Reference Documents

• Debt Categories - Types of technical debt
• Debt Scoring - Impact/effort scoring matrix
• Debt Frontmatter - YAML schema for debt files
• Debt Resolution - Strategies for paying down debt

Core Concepts

What is Technical Debt?

Technical debt is the implied cost of future rework caused by choosing an easy solution now instead of a better approach that would take longer.

Debt Categories

Debt Tracking Location

.claude/debt/
├── INDEX.md                    # Summary and metrics
├── code/
│   ├── DEBT-001-duplicate-validation.md
│   └── DEBT-002-complex-order-service.md
├── architecture/
│   └── DEBT-003-monolith-coupling.md
├── test/
│   └── DEBT-004-payment-coverage.md
├── documentation/
│   └── DEBT-005-api-docs-outdated.md
└── dependency/
    └── DEBT-006-rails-upgrade.md

Debt File Format

---
id: DEBT-001
title: Duplicate validation logic in controllers
category: code
severity: medium
impact: 3
effort: 2
priority: p2
status: open
created: 2024-01-15
tags: [duplication, validation, controllers]
affected_files:
  - app/controllers/orders_controller.rb
  - app/controllers/users_controller.rb
  - app/controllers/products_controller.rb
---

# Duplicate Validation Logic in Controllers

## Description
Validation logic for email, phone, and address is duplicated across multiple controllers instead of being centralized.

## Impact
- **Maintenance**: Changes must be made in multiple places
- **Bugs**: Inconsistent validation between controllers
- **Time**: Extra time reviewing each controller

## Current State
```ruby
# In OrdersController
def validate_email(email)
  email =~ /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i
end

# Same code in UsersController, ProductsController...

Proposed Solution

Extract to a shared validator:

# app/validators/contact_validator.rb
class ContactValidator
  def self.valid_email?(email)
    email =~ EMAIL_REGEX
  end
end

Resolution Steps

1. Create ContactValidator class
2. Add tests for validator
3. Update OrdersController
4. Update UsersController
5. Update ProductsController
6. Remove duplicate code

Related

• DEBT-007: Missing model validations

## Workflow: Scanning for Debt

### Step 1: Identify Debt Indicators

```bash
# Code complexity
find . -name "*.py" -exec wc -l {} \; | sort -rn | head -20

# Duplication
jscpd --reporters html --output .claude/debt/reports/

# TODO/FIXME comments
grep -rn "TODO\|FIXME\|HACK\|XXX" --include="*.py" --include="*.ts"

# Long methods
grep -rn "def \|function " --include="*.py" | head -50

# Test coverage gaps
pytest --cov=. --cov-report=term-missing | grep "MISS"

Step 2: Categorize Findings

For each finding:

1. Determine category (code, architecture, test, etc.)
2. Assess severity (low, medium, high, critical)
3. Estimate impact (1-5)
4. Estimate effort (1-5)
5. Calculate priority

Step 3: Create Debt Files

Create a file in .claude/debt/[category]/ for each item.

Step 4: Update Index

# Technical Debt Index

**Last Updated:** 2024-01-15
**Total Items:** 12
**Open Items:** 10

## Summary by Category

| Category | Open | In Progress | Resolved |
|----------|------|-------------|----------|
| Code | 4 | 1 | 2 |
| Architecture | 2 | 0 | 0 |
| Test | 2 | 0 | 1 |
| Documentation | 1 | 0 | 0 |
| Dependency | 1 | 0 | 0 |

## Priority Distribution

| Priority | Count |
|----------|-------|
| P0 (Critical) | 1 |
| P1 (High) | 3 |
| P2 (Medium) | 4 |
| P3 (Low) | 2 |

## High Priority Items

1. **DEBT-006** [P0] Rails security update required
2. **DEBT-003** [P1] Monolith service coupling
3. **DEBT-001** [P1] Duplicate validation logic

Priority Calculation

Priority Score = Impact × Effort Weight

Impact (1-5):
  5 = Critical (security, data loss risk)
  4 = High (major feature blocked)
  3 = Medium (development slowed)
  2 = Low (minor inconvenience)
  1 = Minimal (cosmetic)

Effort (1-5):
  1 = Hours (quick fix)
  2 = Days (small task)
  3 = Week (medium task)
  4 = Weeks (large task)
  5 = Months (major project)

Priority Mapping:
  Score 15-25: P0 (Critical)
  Score 9-14:  P1 (High)
  Score 4-8:   P2 (Medium)
  Score 1-3:   P3 (Low)

Quick Reference

Debt Indicators

Resolution Strategies