Technical Debt Workflow
Scan, categorize, and prioritize technical debt for systematic reduction.
Workflow
Phase 1: Scan for Debt Indicators
Search for common debt patterns:
TODO/FIXME comments
grep -rn "TODO\|FIXME\|HACK\|XXX" src/
Deprecated patterns
- Old API usage
- Outdated dependencies
- Legacy code patterns
Code smells
- Large files (>500 lines)
- Deeply nested code (>4 levels)
- Duplicate code patterns
- Magic numbers without constants
Missing tests
- Files with no corresponding test file
- Low coverage areas
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
# 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]
1---2name: tech-debt3description: Track, categorize, and prioritize technical debt across the codebase.4---56# Technical Debt Workflow78Scan, categorize, and prioritize technical debt for systematic reduction.910---1112## Workflow1314### Phase 1: Scan for Debt Indicators1516Search for common debt patterns:17181. **TODO/FIXME comments**19 ```20 grep -rn "TODO\|FIXME\|HACK\|XXX" src/21 ```22232. **Deprecated patterns**24 - Old API usage25 - Outdated dependencies26 - Legacy code patterns27283. **Code smells**29 - Large files (>500 lines)30 - Deeply nested code (>4 levels)31 - Duplicate code patterns32 - Magic numbers without constants33344. **Missing tests**35 - Files with no corresponding test file36 - Low coverage areas37385. **Documentation gaps**39 - Missing docstrings40 - Outdated README41 - Missing ADRs for major decisions4243---4445### Phase 2: Categorize Debt4647Group findings by category:4849| Category | Examples |50|----------|----------|51| **Architecture** | Circular dependencies, module boundary violations |52| **Code Quality** | Duplicate code, large functions, magic numbers |53| **Testing** | Missing tests, low coverage, flaky tests |54| **Documentation** | Missing docs, outdated comments |55| **Dependencies** | Outdated packages, security vulnerabilities |56| **Performance** | N+1 queries, unindexed columns, memory leaks |57| **Security** | Hardcoded secrets, missing validation |5859---6061### Phase 3: Assess Severity6263Rate each debt item:6465| Severity | Criteria | Example |66|----------|----------|---------|67| **CRITICAL** | Blocks development or causes production issues | Security vulnerability, data loss risk |68| **HIGH** | Significantly impacts productivity or quality | Missing tests on critical path, broken CI |69| **MEDIUM** | Causes friction but has workaround | Code duplication, missing documentation |70| **LOW** | Nice to fix, low impact | Cosmetic issues, minor optimizations |7172---7374### Phase 4: Estimate Effort7576Estimate time to resolve:7778| Effort | Time | Criteria |79|--------|------|----------|80| **Small** | <2 hours | Localized fix, no dependencies |81| **Medium** | 2-8 hours | Multiple files, some testing needed |82| **Large** | 1-3 days | Architecture change, many files affected |83| **Epic** | >3 days | Major refactor, affects multiple teams |8485---8687### Phase 5: Prioritize8889Calculate priority score:90```91Priority = Severity × Impact / Effort9293CRITICAL = 4, HIGH = 3, MEDIUM = 2, LOW = 194Epic = 4, Large = 3, Medium = 2, Small = 195```9697Higher score = Higher priority to fix.9899---100101### Phase 6: Generate Report102103```markdown104# Technical Debt Report105106## Summary107108- Total Items: [N]109- Critical: [N]110- High: [N]111- Medium: [N]112- Low: [N]113114## Priority Queue115116### Priority 1: CRITICAL Issues117118| ID | Description | Category | Location | Effort |119|----|-------------|----------|----------|--------|120| TD-001 | [Description] | Security | file:line | Medium |121122### Priority 2: HIGH Impact / Low Effort123124| ID | Description | Category | Location | Effort |125|----|-------------|----------|----------|--------|126127### Priority 3: Medium Priority Items128129| ID | Description | Category | Location | Effort |130|----|-------------|----------|----------|--------|131132## By Category133134### Architecture135- [List of architecture debt]136137### Code Quality138- [List of code quality debt]139140### Testing141- [List of testing debt]142143### Documentation144- [List of documentation debt]145146### Dependencies147- [List of dependency debt]148149## Recommended Sprint Allocation150151- **This Sprint**: [Items to tackle now]152- **Next Sprint**: [Items to plan for]153- **Backlog**: [Items to track for later]154155## Debt Reduction Strategy1561571. [Recommended approach for systematic reduction]1582. [Process improvements to prevent new debt]159```
fanlw0816