# Tech Debt

> Track, categorize, and prioritize technical debt across the codebase.

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

---


# Technical Debt Workflow

Scan, categorize, and prioritize technical debt for systematic reduction.

---

## Workflow

### Phase 1: Scan for Debt Indicators

Search for common debt patterns:

1. **TODO/FIXME comments**
   ```
   grep -rn "TODO\|FIXME\|HACK\|XXX" src/
   ```

2. **Deprecated patterns**
   - Old API usage
   - Outdated dependencies
   - Legacy code patterns

3. **Code smells**
   - Large files (>500 lines)
   - Deeply nested code (>4 levels)
   - Duplicate code patterns
   - Magic numbers without constants

4. **Missing tests**
   - Files with no corresponding test file
   - Low coverage areas

5. **Documentation gaps**
   - Missing docstrings
   - Outdated README
   - Missing ADRs for major decisions

---

### Phase 2: Categorize Debt

Group findings by category:

| Category | Examples |
|----------|----------|
| **Architecture** | Circular dependencies, module boundary violations |
| **Code Quality** | Duplicate code, large functions, magic numbers |
| **Testing** | Missing tests, low coverage, flaky tests |
| **Documentation** | Missing docs, outdated comments |
| **Dependencies** | Outdated packages, security vulnerabilities |
| **Performance** | N+1 queries, unindexed columns, memory leaks |
| **Security** | Hardcoded secrets, missing validation |

---

### Phase 3: Assess Severity

Rate each debt item:

| Severity | Criteria | Example |
|----------|----------|---------|
| **CRITICAL** | Blocks development or causes production issues | Security vulnerability, data loss risk |
| **HIGH** | Significantly impacts productivity or quality | Missing tests on critical path, broken CI |
| **MEDIUM** | Causes friction but has workaround | Code duplication, missing documentation |
| **LOW** | Nice to fix, low impact | Cosmetic issues, minor optimizations |

---

### Phase 4: Estimate Effort

Estimate time to resolve:

| Effort | Time | Criteria |
|--------|------|----------|
| **Small** | <2 hours | Localized fix, no dependencies |
| **Medium** | 2-8 hours | Multiple files, some testing needed |
| **Large** | 1-3 days | Architecture change, many files affected |
| **Epic** | >3 days | Major refactor, affects multiple teams |

---

### Phase 5: Prioritize

Calculate priority score:
```
Priority = Severity × Impact / Effort

CRITICAL = 4, HIGH = 3, MEDIUM = 2, LOW = 1
Epic = 4, Large = 3, Medium = 2, Small = 1
```

Higher score = Higher priority to fix.

---

### Phase 6: Generate Report

```markdown
# Technical Debt Report

## Summary

- Total Items: [N]
- Critical: [N]
- High: [N]
- Medium: [N]
- Low: [N]

## Priority Queue

### Priority 1: CRITICAL Issues

| ID | Description | Category | Location | Effort |
|----|-------------|----------|----------|--------|
| TD-001 | [Description] | Security | file:line | Medium |

### Priority 2: HIGH Impact / Low Effort

| ID | Description | Category | Location | Effort |
|----|-------------|----------|----------|--------|

### Priority 3: Medium Priority Items

| ID | Description | Category | Location | Effort |
|----|-------------|----------|----------|--------|

## By Category

### Architecture
- [List of architecture debt]

### Code Quality
- [List of code quality debt]

### Testing
- [List of testing debt]

### Documentation
- [List of documentation debt]

### Dependencies
- [List of dependency debt]

## Recommended Sprint Allocation

- **This Sprint**: [Items to tackle now]
- **Next Sprint**: [Items to plan for]
- **Backlog**: [Items to track for later]

## Debt Reduction Strategy

1. [Recommended approach for systematic reduction]
2. [Process improvements to prevent new debt]
```