Tech Debt Skill
Goal
Surface, document, and prioritize technical debt so it can be systematically planned and repaid. Produce an Impact×Effort prioritized backlog using TECH_DEBT_TEMPLATE.md.
Steps
Scan for explicit debt markers
# Find all TODO, FIXME, HACK, XXX markers
grep -rn "TODO\|FIXME\|HACK\|XXX\|@deprecated\|@todo" src/ --include="*.ts" --include="*.php" --include="*.py"
For each marker: note file:line, understand context, assign Impact and Effort scores.
Run complexity analysis
# JavaScript/TypeScript
npx complexity-report --format json src/ > complexity-report.json
# Look for: functions with cyclomatic complexity > 10
# PHP
vendor/bin/phpmd app/ text codesize,complexity
# Python
radon cc src/ -a -s # Cyclomatic complexity
xenon --max-absolute B --max-modules A --max-average A src/
# Look for: NPathComplexity > 200, CyclomaticComplexity > 10
# SonarQube (if configured)
sonar-scanner
# Look for: cognitive complexity, code smells
Check code duplication
# JavaScript/TypeScript
npx jscpd src/ --min-lines 5 --min-tokens 50
# PHP
vendor/bin/phpcpd app/
# Flag: any duplication > 3 occurrences → candidate for extraction
Check test coverage gaps
[test coverage command]
# Flag files with < 60% line coverage as test debt
Identify structural debt patterns
God objects (too many responsibilities):
- Classes > 500 lines or > 20 public methods
- Files that import from > 15 other files (high fan-in = too many dependencies)
Fat Controllers (business logic in wrong layer):
- Controllers with > 50 lines of business logic
- Bypass of use-case/service layer
Missing abstractions:
- Repeated patterns without an abstraction (violates DRY after 3rd occurrence)
- Hardcoded config values that should be constants or env vars
Stale dependencies:
npm outdated # Node.js — shows current vs wanted vs latest
composer outdated # PHP
pip list --outdated # Python
Score each debt item using Impact×Effort matrix
Impact (how much does this hurt development?):
H = blocks development, causes bugs, creates security risk
M = slows development, increases maintenance burden
L = minor annoyance, cosmetic
Effort (how long to fix?):
H = days or weeks of work
M = hours of focused work
L = < 1 hour
Priority matrix:
High Impact + Low Effort = P1 (do immediately)
High Impact + High Effort = P2 (plan for next sprint)
Low Impact + Low Effort = P3 (good for juniors/onboarding)
Low Impact + High Effort = P4 (deprioritize or skip)
Fill TECH_DEBT_TEMPLATE.md for each debt item
Produce prioritized backlog
## Tech Debt Backlog — [Date]
### P1 — High Impact, Low Effort (do now)
- TD-001: Extract UserValidator from UserController (2h effort, removes security bug risk)
### P2 — High Impact, High Effort (plan next sprint)
- TD-002: Refactor OrderService God class (3 days, blocks all new order features)
### P3 — Low Impact, Low Effort (good first issues)
- TD-003: Replace magic numbers in pricing module with named constants (30min)
### P4 — Deprioritize
- TD-004: Rename legacy variable names in archived report module (low business value)
Add P1 and P2 items to project/tasks.md
- Create atomic tasks (15-min rule) for each debt item
- Link to TECH_DEBT_TEMPLATE.md entry
Constraints
- Never fix tech debt in the same commit as a feature or bug fix
- Refactoring must be accompanied by passing tests (test guard)
- Tech debt items must be tracked — don't fix and forget (update TECH_DEBT_TEMPLATE)
- Always measure complexity BEFORE and AFTER to verify improvement
Output Format
Filled TECH_DEBT_TEMPLATE.md entries + prioritized backlog. Report: "Found [N] debt items. P1: [N], P2: [N], P3: [N], P4: [N]."
1---2name: tech-debt-43description: Identify, document, score, and prioritize technical debt into an actionable backlog4---5
6# Tech Debt Skill
7
8## Goal
9Surface, document, and prioritize technical debt so it can be systematically planned and repaid. Produce an Impact×Effort prioritized backlog using TECH_DEBT_TEMPLATE.md.
10
11## Steps
12
131. **Scan for explicit debt markers**
14 ```bash
15 # Find all TODO, FIXME, HACK, XXX markers
16 grep -rn "TODO\|FIXME\|HACK\|XXX\|@deprecated\|@todo" src/ --include="*.ts" --include="*.php" --include="*.py"
17 ```
18 For each marker: note file:line, understand context, assign Impact and Effort scores.
19
202. **Run complexity analysis**
21 ```bash
22 # JavaScript/TypeScript
23 npx complexity-report --format json src/ > complexity-report.json
24 # Look for: functions with cyclomatic complexity > 10
25
26 # PHP
27 vendor/bin/phpmd app/ text codesize,complexity
28
29 # Python
30 radon cc src/ -a -s # Cyclomatic complexity
31 xenon --max-absolute B --max-modules A --max-average A src/
32 # Look for: NPathComplexity > 200, CyclomaticComplexity > 10
33
34 # SonarQube (if configured)
35 sonar-scanner
36 # Look for: cognitive complexity, code smells
37 ```
38
393. **Check code duplication**
40 ```bash
41 # JavaScript/TypeScript
42 npx jscpd src/ --min-lines 5 --min-tokens 50
43
44 # PHP
45 vendor/bin/phpcpd app/
46
47 # Flag: any duplication > 3 occurrences → candidate for extraction
48 ```
49
504. **Check test coverage gaps**
51 ```bash
52 [test coverage command]
53 # Flag files with < 60% line coverage as test debt
54 ```
55
565. **Identify structural debt patterns**
57
58 **God objects** (too many responsibilities):
59 - Classes > 500 lines or > 20 public methods
60 - Files that import from > 15 other files (high fan-in = too many dependencies)
61
62 **Fat Controllers** (business logic in wrong layer):
63 - Controllers with > 50 lines of business logic
64 - Bypass of use-case/service layer
65
66 **Missing abstractions**:
67 - Repeated patterns without an abstraction (violates DRY after 3rd occurrence)
68 - Hardcoded config values that should be constants or env vars
69
70 **Stale dependencies**:
71 ```bash
72 npm outdated # Node.js — shows current vs wanted vs latest
73 composer outdated # PHP
74 pip list --outdated # Python
75 ```
76
776. **Score each debt item** using Impact×Effort matrix
78
79 ```
80 Impact (how much does this hurt development?):
81 H = blocks development, causes bugs, creates security risk
82 M = slows development, increases maintenance burden
83 L = minor annoyance, cosmetic
84
85 Effort (how long to fix?):
86 H = days or weeks of work
87 M = hours of focused work
88 L = < 1 hour
89
90 Priority matrix:
91 High Impact + Low Effort = P1 (do immediately)
92 High Impact + High Effort = P2 (plan for next sprint)
93 Low Impact + Low Effort = P3 (good for juniors/onboarding)
94 Low Impact + High Effort = P4 (deprioritize or skip)
95 ```
96
977. **Fill TECH_DEBT_TEMPLATE.md** for each debt item
98
998. **Produce prioritized backlog**
100 ```markdown
101 ## Tech Debt Backlog — [Date]
102
103 ### P1 — High Impact, Low Effort (do now)
104 - TD-001: Extract UserValidator from UserController (2h effort, removes security bug risk)
105
106 ### P2 — High Impact, High Effort (plan next sprint)
107 - TD-002: Refactor OrderService God class (3 days, blocks all new order features)
108
109 ### P3 — Low Impact, Low Effort (good first issues)
110 - TD-003: Replace magic numbers in pricing module with named constants (30min)
111
112 ### P4 — Deprioritize
113 - TD-004: Rename legacy variable names in archived report module (low business value)
114 ```
115
1169. **Add P1 and P2 items to project/tasks.md**
117 - Create atomic tasks (15-min rule) for each debt item
118 - Link to TECH_DEBT_TEMPLATE.md entry
119
120## Constraints
121- Never fix tech debt in the same commit as a feature or bug fix
122- Refactoring must be accompanied by passing tests (test guard)
123- Tech debt items must be tracked — don't fix and forget (update TECH_DEBT_TEMPLATE)
124- Always measure complexity BEFORE and AFTER to verify improvement
125
126## Output Format
127Filled TECH_DEBT_TEMPLATE.md entries + prioritized backlog. Report: "Found [N] debt items. P1: [N], P2: [N], P3: [N], P4: [N]."
majiayu000