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