Technical Debt Analyzer
Systematically identify, analyze, and document technical debt.
When to Use
Use for:
- Analyzing code quality issues
- Creating technical debt registers
- Assessing code maintainability
- Identifying dependency problems
- Documenting security vulnerabilities
- Planning refactoring efforts
Don't use when:
- Writing new code → use
generic-feature-developer
- Code review → use
generic-code-reviewer
- Writing tests → use
test-specialist
Quick Analysis Commands
# Find large files (>500 lines)
find src -name "*.ts" -exec wc -l {} + | awk '$1 > 500' | sort -rn
# Find TODO/FIXME markers
grep -rn "TODO\|FIXME\|HACK\|XXX" src/
# Check for console.log in production code
grep -rn "console.log" src/ --include="*.ts" --include="*.tsx"
# Find TypeScript 'any' usage
grep -rn ": any" src/ --include="*.ts" --include="*.tsx"
# Check outdated dependencies
npm outdated
# Security vulnerabilities
npm audit
# Unused exports (requires ts-unused-exports)
npx ts-unused-exports tsconfig.json
Debt Categories
| Category |
Examples |
| Code Quality |
Large files, complex functions, TODO/FIXME markers |
| Architectural |
Tight coupling, missing abstractions, circular deps |
| Test |
Missing coverage, fragile tests, slow execution |
| Documentation |
Missing README, outdated docs, no ADRs |
| Dependency |
Outdated packages, security vulnerabilities |
| Performance |
N+1 queries, memory leaks, large bundles |
| Security |
Missing validation, exposed secrets, XSS/SQL injection |
Analysis Workflow
1. Automated Detection
Code Smells to Check:
- Large files (>500 lines)
- Complex functions (cyclomatic complexity >10)
- Debt markers (TODO, FIXME, HACK, XXX)
- Console statements in production code
any types in TypeScript- Long parameter lists (>5 params)
- Deep nesting (>4 levels)
Dependency Issues:
- Deprecated packages
- Duplicate functionality
- Loose version constraints
- Known vulnerabilities
2. Severity Assessment
| Severity |
Criteria |
Action |
| Critical |
Security vulns, data loss risk |
Immediate fix |
| High |
Performance problems, blocking issues |
Current sprint |
| Medium |
Code quality, missing docs |
This quarter |
| Low |
Minor smells, optimizations |
When convenient |
3. Priority Matrix
| Impact / Effort |
Low |
Medium |
High |
| High Impact |
Do First |
Do Second |
Plan & Do |
| Medium Impact |
Do Second |
Plan & Do |
Consider |
| Low Impact |
Quick Win |
Consider |
Avoid |
Debt Register Format
## DEBT-001: Description
**Category:** Code Quality | **Severity:** High
**Location:** src/services/UserService.ts
**Description:** Brief description of the issue
**Impact:**
- Business: How it affects delivery
- Technical: Why it's problematic
- Risk: What could go wrong
**Proposed Solution:** What to do about it
**Effort:** Days/hours estimate
**Target:** Sprint/quarter
Prevention Strategies
Automated Guards
{
"rules": {
"complexity": ["error", 10],
"max-lines-per-function": ["error", 50],
"max-params": ["error", 5],
"max-depth": ["error", 4]
}
}
Maintenance Schedule
| Frequency |
Tasks |
| Weekly |
Review TODO/FIXME, update register |
| Monthly |
Dependency updates, debt review |
| Quarterly |
Full analysis, architecture review |
Self-Critique Checklist
After completing debt analysis:
See Also
1---2name: tech-debt-analyzer3description: This skill should be used when analyzing technical debt in a codebase, documenting code quality issues, creating technical debt registers, or assessing code maintainability. Use this for identifying code smells, architectural issues, dependency problems, missing documentation, security vulnerabilities, and creating comprehensive technical debt documentation.4---5
6# Technical Debt Analyzer
7
8Systematically identify, analyze, and document technical debt.
9
10## When to Use
11
12**Use for:**
13
14- Analyzing code quality issues
15- Creating technical debt registers
16- Assessing code maintainability
17- Identifying dependency problems
18- Documenting security vulnerabilities
19- Planning refactoring efforts
20
21**Don't use when:**
22
23- Writing new code → use `generic-feature-developer`
24- Code review → use `generic-code-reviewer`
25- Writing tests → use `test-specialist`
26
27## Quick Analysis Commands
28
29```bash
30# Find large files (>500 lines)
31find src -name "*.ts" -exec wc -l {} + | awk '$1 > 500' | sort -rn
32
33# Find TODO/FIXME markers
34grep -rn "TODO\|FIXME\|HACK\|XXX" src/
35
36# Check for console.log in production code
37grep -rn "console.log" src/ --include="*.ts" --include="*.tsx"
38
39# Find TypeScript 'any' usage
40grep -rn ": any" src/ --include="*.ts" --include="*.tsx"
41
42# Check outdated dependencies
43npm outdated
44
45# Security vulnerabilities
46npm audit
47
48# Unused exports (requires ts-unused-exports)
49npx ts-unused-exports tsconfig.json
50```
51
52## Debt Categories
53
54| Category | Examples |
55| ------------- | ------------------------------------------------------ |
56| Code Quality | Large files, complex functions, TODO/FIXME markers |
57| Architectural | Tight coupling, missing abstractions, circular deps |
58| Test | Missing coverage, fragile tests, slow execution |
59| Documentation | Missing README, outdated docs, no ADRs |
60| Dependency | Outdated packages, security vulnerabilities |
61| Performance | N+1 queries, memory leaks, large bundles |
62| Security | Missing validation, exposed secrets, XSS/SQL injection |
63
64## Analysis Workflow
65
66### 1. Automated Detection
67
68**Code Smells to Check:**
69
70- Large files (>500 lines)
71- Complex functions (cyclomatic complexity >10)
72- Debt markers (TODO, FIXME, HACK, XXX)
73- Console statements in production code
74- `any` types in TypeScript
75- Long parameter lists (>5 params)
76- Deep nesting (>4 levels)
77
78**Dependency Issues:**
79
80- Deprecated packages
81- Duplicate functionality
82- Loose version constraints
83- Known vulnerabilities
84
85### 2. Severity Assessment
86
87| Severity | Criteria | Action |
88| -------- | ------------------------------------- | --------------- |
89| Critical | Security vulns, data loss risk | Immediate fix |
90| High | Performance problems, blocking issues | Current sprint |
91| Medium | Code quality, missing docs | This quarter |
92| Low | Minor smells, optimizations | When convenient |
93
94### 3. Priority Matrix
95
96| Impact / Effort | Low | Medium | High |
97| --------------- | --------- | --------- | --------- |
98| High Impact | Do First | Do Second | Plan & Do |
99| Medium Impact | Do Second | Plan & Do | Consider |
100| Low Impact | Quick Win | Consider | Avoid |
101
102## Debt Register Format
103
104```markdown
105## DEBT-001: Description
106
107**Category:** Code Quality | **Severity:** High
108**Location:** src/services/UserService.ts
109
110**Description:** Brief description of the issue
111
112**Impact:**
113
114- Business: How it affects delivery
115- Technical: Why it's problematic
116- Risk: What could go wrong
117
118**Proposed Solution:** What to do about it
119**Effort:** Days/hours estimate
120**Target:** Sprint/quarter
121```
122
123## Prevention Strategies
124
125### Automated Guards
126
127```json
128{
129 "rules": {
130 "complexity": ["error", 10],
131 "max-lines-per-function": ["error", 50],
132 "max-params": ["error", 5],
133 "max-depth": ["error", 4]
134 }
135}
136```
137
138### Maintenance Schedule
139
140| Frequency | Tasks |
141| --------- | ---------------------------------- |
142| Weekly | Review TODO/FIXME, update register |
143| Monthly | Dependency updates, debt review |
144| Quarterly | Full analysis, architecture review |
145
146## Self-Critique Checklist
147
148After completing debt analysis:
149
150- [ ] All automated checks run
151- [ ] Manual review of critical paths done
152- [ ] Severity assessments justified
153- [ ] Proposed solutions are actionable
154- [ ] Priority matrix applied consistently
155- [ ] Register entries are complete
156
157## See Also
158
159- [Code Review Standards](../_shared/CODE_REVIEW_STANDARDS.md) - Quality checks
160- Project `CLAUDE.md` - Workflow rules
travisjneuman