# Tech Debt

> Technical debt identification, prioritization, and strategic repayment planning.

- Skill: `lst97/tech-debt` (Agent Skill)
- Install (CLI): `npx skillmds@latest add lst97/tech-debt`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lst97/tech-debt/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: lst97 (https://skillmd.com/u/lst97)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/lst97/tech-debt

---


# Tech Debt Skill

## Purpose

To transform **silent code rot** into **managed, prioritized backlog items**. This skill provides a systematic approach to identifying, quantifying, and scheduling technical debt repayment—preventing the "big bang" rewrite and enabling sustainable development velocity.

**ROI Metric**: Addressing debt early costs 1x. Addressing it late costs 10x. Ignoring it costs 100x (failed projects).

## When to Use

- **Trigger**: When velocity is slowing down (features taking longer).
- **Trigger**: When `reflexion` identifies recurring issues.
- **Trigger**: Before major feature work ("Clean the campsite first").
- **Trigger**: When code complexity metrics exceed thresholds.
- **Trigger**: When `pm-agent` schedules a "debt sprint."

## The Debt Management Protocol (The 4-Step Process)

### 1. Identification (Where Is The Debt?)

**Scan for these debt signals:**

| Signal | Detection Method | Example |
|:-------|:-----------------|:--------|
| **Code Smells** | Static analysis, complexity metrics | Functions >50 lines, nested conditionals >3 levels |
| **Outdated Dependencies** | `npm outdated`, `cargo outdated` | React 16 when 18 is available |
| **Missing Tests** | Coverage reports | Critical path has <50% coverage |
| **Documentation Drift** | Doc vs code comparison | API docs don't match implementation |
| **Workarounds** | Code comments (`// HACK`, `// FIXME`) | Temporary fixes that became permanent |
| **Performance Issues** | Profiling, metrics | Page load >3s, API latency >500ms |
| **Security Vulnerabilities** | `npm audit`, SAST scans | Known CVEs in dependencies |

### 2. Quantification (How Bad Is It?)

Score each debt item across three dimensions:

**Impact (1-10)**: How much does this hurt?
- Development velocity
- System reliability
- Security posture
- User experience

**Effort (1-10)**: How hard to fix?
- Lines of code to change
- Files affected
- Dependencies to update
- Tests to write
- Risk of breaking changes

**Interest Rate (1-10)**: How fast is it growing?
- How often does this code change?
- How many new features touch this area?
- How many workarounds are being added?

**Debt Score = Impact × Interest Rate / Effort**

Higher score = Pay this debt first.

### 3. Categorization (What Type Of Debt?)

| Category | Description | Example | Typical Action |
|:---------|:------------|:--------|:-------------|
| **Design Debt** | Architectural shortcuts | God class, tight coupling | Refactor with ADR |
| **Code Debt** | Implementation shortcuts | Copy-pasted code, long methods | Refactor incrementally |
| **Test Debt** | Missing or poor tests | No integration tests | Write tests before changes |
| **Documentation Debt** | Outdated or missing docs | API changes not documented | Update docs as you go |
| **Dependency Debt** | Outdated libraries | React 16 in 2026 | Scheduled upgrade |
| **Infrastructure Debt** | Ops shortcuts | Manual deploys | Automate via IaC |
| **Skill Debt** | Team knowledge gaps | No one knows GraphQL | Training + pairing |

### 4. Scheduling (When Do We Pay?)

**Strategies:**

**A. Debt Sprints (20% Rule)**
- Reserve 20% of every sprint for debt repayment.
- Pay highest-scored debt items first.
- Track debt burndown like feature burndown.

**B. Boy Scout Rule**
- "Leave the code better than you found it."
- Small improvements with every feature PR.
- Limit: 10-20% of PR scope should be cleanup.

**C. Before New Features**
- Clean debt in the area you're about to modify.
- Prevents building on shaky foundations.

**D. Scheduled Maintenance**
- Quarterly dependency updates.
- Bi-annual architecture reviews.
- Annual security audits.

## Debt Item Template

```markdown
# Tech Debt Item: [TITLE]

## Summary
**ID**: DEBT-XXX  
**Category**: [Design/Code/Test/Doc/Dependency/Infra/Skill]  
**Filed Date**: YYYY-MM-DD  
**Status**: Identified | Scheduled | In Progress | Paid

## Problem Statement
[What is the debt? What are the symptoms?]

[Example: The UserService class has grown to 2000 lines and handles authentication, profile management, and preferences. Changes require touching 15+ methods.]

## Impact Assessment

| Dimension | Score (1-10) | Justification |
|:----------|:------------:|:--------------|
| **Impact** | 8 | Every user feature touches this class. Changes are slow and error-prone. |
| **Effort** | 6 | Requires splitting into 3-4 services. Estimated 3 days. |
| **Interest Rate** | 9 | We add 2-3 new user features per sprint. Debt grows fast. |

**Debt Score**: (8 × 9) / 6 = **12.0** [Pay Immediately: >10]

## Symptoms
- [ ] Feature X took 5 days instead of 2
- [ ] Bug Y introduced because of tight coupling
- [ ] Developer onboarding takes 3 days to understand UserService
- [ ] Tests are flaky due to too many responsibilities

## Proposed Solution
[What should we do to pay this debt?]

[Example: Split UserService into AuthService, ProfileService, and PreferenceService. Each <300 lines.]

### Steps
1. [ ] Step 1: Create ProfileService, move profile methods
2. [ ] Step 2: Update tests for ProfileService
3. [ ] Step 3: Create PreferenceService, move preference methods
4. [ ] Step 4: Update tests for PreferenceService
5. [ ] Step 5: Refactor UserService to AuthService only
6. [ ] Step 6: Update all imports and calls
7. [ ] Step 7: Verify all tests pass

## Risks & Mitigations
- **Risk**: Breaking changes to API → Mitigation: Maintain backward-compatible wrapper during transition
- **Risk**: Tests need major rewrite → Mitigation: Write new service tests before migration

## Payment Schedule
- **Strategy**: Before New Feature
- **Scheduled Sprint**: Sprint 12 (when we build User Preferences v2)
- **Owner**: @backend-team
- **Estimated Effort**: 3 days

## Notes
- **Related PRs**: #123, #456
- **Related ADRs**: ADR-002 (Service Boundaries)
- **Outcome (when paid)**: [To be filled]
```

## Execution Template

*Use this when running a debt audit.*

```markdown
## 🔍 Tech Debt Audit: [Scope]

### 1. Scan Results

| ID | Category | Location | Impact | Effort | Interest | Score | Priority |
|:---|:---------|:---------|:------:|:------:|:--------:|:-----:|:--------:|
| D-001 | Design | UserService.ts | 8 | 6 | 9 | 12.0 | HIGH |
| D-002 | Dependency | React 16.x | 6 | 4 | 7 | 10.5 | HIGH |
| D-003 | Test | auth/ | 7 | 3 | 6 | 14.0 | HIGH |
| D-004 | Code | utils/helpers.js | 4 | 2 | 3 | 6.0 | MEDIUM |

### 2. High Priority Items (Score >10)

#### D-003: Missing Auth Tests
**Problem**: Authentication flows have 23% test coverage.  
**Impact**: Every auth change risks regression.  
**Solution**: Write integration tests for all auth flows.  
**Effort**: 2 days  
**Schedule**: Next sprint (Sprint 11)

### 3. Payment Plan

**This Sprint (Sprint 10)**
- [ ] D-004: Refactor utils/helpers.js (1 day)
- Feature work: 80%
- Debt work: 20%

**Next Sprint (Sprint 11)**
- [ ] D-003: Auth test coverage (2 days)
- [ ] D-002: React upgrade planning (1 day)
- Feature work: 70%
- Debt work: 30%

**Following Sprint (Sprint 12)**
- [ ] D-001: Split UserService (3 days)
- Feature work: 60%
- Debt work: 40%

### 4. Debt Metrics
- **Total Items**: 4
- **High Priority**: 3
- **Estimated Total Effort**: 12 days
- **Debt Burndown Target**: 0 high-priority items by end of Q2
```

## Debt Register

Maintain a central debt register:

```markdown
# Technical Debt Register

## Active Debt
| ID | Title | Category | Score | Status | Owner | Target Sprint |
|:---|:------|:---------|:-----:|:-------|:------|:-------------:|
| D-001 | UserService too large | Design | 12.0 | Scheduled | Backend | 12 |
| D-002 | React 16 outdated | Dependency | 10.5 | Scheduled | Frontend | 11 |
| D-003 | Auth tests missing | Test | 14.0 | In Progress | Quality | 11 |

## Recently Paid
| ID | Title | Category | Paid Date | Effort | Outcome |
|:---|:------|:---------|:----------|:-------|:--------|
| D-000 | Legacy API wrapper | Code | 2026-01-15 | 2 days | API response time -30% |
```

## Integration with Agents

- **`architect`**: Identifies design debt, creates ADRs for major refactors.
- **`backend` / `frontend`**: Identifies code debt during implementation.
- **`quality`**: Identifies test debt from coverage reports.
- **`pm-agent`**: Schedules debt sprints, tracks debt burndown.
- **`reflexion`**: Surfaces recurring issues that become debt items.

## Anti-Patterns (Avoid)

- ❌ **"We'll fix it later"** without scheduling → Becomes permanent
- ❌ **Big Bang Rewrite** → High risk, hard to validate
- ❌ **Perfect is Enemy of Good** → Don't gold-plate while debt accumulates
- ❌ **Debt Amnesty** → Don't ignore debt because "it's always been there"
- ❌ **Paying Low-Score Debt First** → Focus on high-impact, high-interest debt