User Input

text
1$ARGUMENTS

You MUST consider the user input before proceeding (if not empty).

Usage Modes

Category Filter Values

Goal

Perform a comprehensive technical debt analysis that answers: What maintenance burden exists in this code?

This skill orchestrates 10 specialized agents in parallel to analyze:

• Code complexity and maintainability
• Dead code and unused symbols
• Dependency health and security
• Documentation gaps
• Testing debt
• TODO/FIXME archaeology
• Git hotspots and churn
• Performance anti-patterns
• Architecture smells

Results are synthesized into a prioritized, actionable report with trend tracking.

Operating Constraints

STRICTLY READ-ONLY: Do not modify any files. Output analysis and recommendations.

PARALLEL EXECUTION: Launch all applicable agents in a single message for efficiency.

TREND TRACKING: Full audits are saved to .claude/reviews/ for historical comparison.

Constitution Alignment

This skill validates adherence to project principles:

• Quality: Maintain high code quality standards
• Maintainability: Keep technical debt manageable
• Security: No known vulnerabilities in dependencies

Memory Integration

After Completion (Full Audit Only)

Save audit findings for trend analysis:

bash
1./scripts/memory-save --decisions "Tech debt audit: Score {score}/100, {critical} critical issues, top areas: {categories}" --issues "{LinearIDs}"

Execution Steps

Phase 0: Scope Determination

You handle this phase directly.

Parse user input to determine mode:

1. If --all flag present: Full codebase audit

   bash
   1# Get all Python files
   2find packages/ plugins/ -name "*.py" -type f 2>/dev/null | wc -l

2. If specific path provided: Targeted directory

   bash
   1# Verify path exists and count files
   2find <provided-path> -name "*.py" -type f 2>/dev/null | wc -l

3. If --category=<name> present: Extract category for filtering

4. Default (no args): Changed files only

   bash
   1# Get changed Python files
   2git diff --name-only main...HEAD | grep '\.py$'

Report mode to user:

• --all mode: "Running FULL CODEBASE audit on N Python files"
• Specific path: "Analyzing directory: <path> (N files)"
• --category=X: "Running single-category analysis: X"
• Default: "Analyzing N files changed vs main"

If no files to analyze in default mode, suggest using --all for full audit.

Phase 1: Check for Prior Audits (Trend Tracking)

Only for --all mode:

bash
1# Find most recent audit
2ls -t .claude/reviews/tech-debt-*.json 2>/dev/null | head -1

If prior audit exists, load it for trend comparison in Phase 3.

Phase 2: Parallel Analysis

Invoke agents IN PARALLEL (single message, multiple Task calls):

Based on --category filter (or all if no filter):

# Haiku agents (fast, single-file analysis)
Task(todo-archaeology, "Analyze TODO/FIXME/HACK comments...
Files: [list or scope]
Return archaeology report with age analysis.")

Task(documentation-debt-analyzer, "Analyze documentation gaps...
Files: [list or scope]
Return documentation debt report.")

Task(code-complexity-analyzer, "Analyze code complexity...
Files: [list or scope]
Return complexity metrics report.")

# Sonnet agents (cross-file analysis)
Task(dead-code-detector, "Detect unreachable and unused code...
Files: [list or scope]
Return dead code report.")

Task(dependency-debt-analyzer, "Analyze dependency health...
Scope: [package dirs]
Return dependency health report.")

Task(testing-debt-analyzer, "Analyze test coverage and quality gaps...
Files: [list or scope]
Return testing debt report.")

Task(git-hotspot-analyzer, "Analyze git history for hotspots and churn...
Files: [list or scope]
Return hotspot analysis report.")

Task(performance-debt-detector, "Detect performance anti-patterns...
Files: [list or scope]
Return performance debt report.")

# Existing agents (reused)
Task(code-pattern-reviewer, "Analyze module patterns and architecture...
Files: [list or scope]
Return architecture pattern report.")

Task(test-duplication-detector, "Detect test duplication...
Files: [list or scope]
Return test duplication report.")

Wait for all agents to return.

Phase 3: Synthesis

You handle this phase directly.

1. Aggregate findings from all agent reports
2. Classify by severity using .claude/skills/tech-debt-review/references/severity-criteria.md
3. Calculate debt score (0-100, where 100 = no debt):
   • Start at 100
   • CRITICAL issues: -10 each (max -40)
   • HIGH issues: -5 each (max -30)
   • MEDIUM issues: -2 each (max -20)
   • LOW issues: -1 each (max -10)
4. Prioritize by Risk x Impact / Effort (see references/prioritization.md)
5. Compare trends if prior audit exists

Phase 4: Persistence (Full Audit Mode Only)

Only for --all mode:

Save audit snapshot:

bash
1# Generate timestamp
2TIMESTAMP=$(date +%Y%m%d-%H%M%S)
3
4# Save audit to .claude/reviews/tech-debt-${TIMESTAMP}.json

Storage Format:

json
1{
2  "timestamp": "2026-01-22T10:30:00Z",
3  "scope": "full-audit",
4  "branch": "main",
5  "commit": "<git-hash>",
6  "debt_score": 72,
7  "categories": {
8    "complexity": {"issues": 8, "critical": 1, "high": 2, "medium": 3, "low": 2},
9    "dead_code": {"issues": 3, "critical": 0, "high": 1, "medium": 2, "low": 0},
10    "dependencies": {"issues": 5, "critical": 2, "high": 1, "medium": 1, "low": 1},
11    "documentation": {"issues": 7, "critical": 0, "high": 0, "medium": 4, "low": 3},
12    "testing": {"issues": 12, "critical": 0, "high": 3, "medium": 5, "low": 4},
13    "todos": {"issues": 15, "critical": 0, "high": 2, "medium": 8, "low": 5},
14    "hotspots": {"issues": 4, "critical": 1, "high": 1, "medium": 2, "low": 0},
15    "performance": {"issues": 6, "critical": 0, "high": 2, "medium": 3, "low": 1},
16    "architecture": {"issues": 4, "critical": 1, "high": 1, "medium": 1, "low": 1}
17  },
18  "total_issues": 64,
19  "critical_issues": 5,
20  "remediation_days": 15
21}

Output Format

markdown
1## Technical Debt Review
2
3**Scope**: [PR: 15 files | Full Audit: 234 files | Directory: path/ (45 files)]
4**Debt Score**: 72/100 (Good)
5**Estimated Remediation**: 15 person-days
6**Trend**: [+5 vs last audit | First audit | N/A for PR mode]
7
8---
9
10### Executive Summary
11
12| Category | Issues | Critical | High | Trend |
13|----------|--------|----------|------|-------|
14| Complexity | 8 | 1 | 2 | [arrow] |
15| Dead Code | 3 | 0 | 1 | [arrow] |
16| Dependencies | 5 | 2 | 1 | [arrow] |
17| Documentation | 7 | 0 | 0 | [arrow] |
18| Testing | 12 | 0 | 3 | [arrow] |
19| TODOs | 15 | 0 | 2 | [arrow] |
20| Hotspots | 4 | 1 | 1 | [arrow] |
21| Performance | 6 | 0 | 2 | [arrow] |
22| Architecture | 4 | 1 | 1 | [arrow] |
23
24**Trend Legend**: [up-arrow] worse | [down-arrow] better | [right-arrow] stable | - no prior data
25
26---
27
28### Priority Actions (Fix These First)
29
30| Priority | Issue | Category | File:Line | Impact | Effort |
31|----------|-------|----------|-----------|--------|--------|
32| P0 | CVE-2024-XXXXX in package X | Dependencies | pyproject.toml | Critical | Low |
33| P0 | God class (15+ methods) | Architecture | compiler.py:45 | High | Medium |
34| P1 | 45% test coverage gap | Testing | service.py | High | High |
35| P1 | N+1 query pattern | Performance | repository.py:123 | High | Medium |
36| P2 | TODO from 2024 | TODOs | utils.py:67 | Medium | Low |
37
38---
39
40### Detailed Findings by Category
41
42#### Code Complexity (8 issues)
43
44[Agent report summary]
45
46**Critical/High Issues:**
47- `file.py:123` - Cyclomatic complexity 25 (threshold: 10)
48- `file.py:456` - Cognitive complexity 32 (threshold: 15)
49
50#### Dead Code (3 issues)
51
52[Agent report summary]
53
54#### Dependencies (5 issues)
55
56[Agent report summary]
57
58**Security Vulnerabilities:**
59- CVE-2024-XXXXX in `package==1.2.3` (CRITICAL)
60
61#### Documentation (7 issues)
62
63[Agent report summary]
64
65#### Testing Debt (12 issues)
66
67[Agent report summary]
68
69#### TODO Archaeology (15 issues)
70
71[Agent report summary]
72
73**Oldest TODOs:**
74- `file.py:45` - "TODO: Fix this" (18 months old)
75
76#### Git Hotspots (4 issues)
77
78[Agent report summary]
79
80**High Churn Files:**
81- `compiler.py` - 45 changes in 3 months
82
83#### Performance (6 issues)
84
85[Agent report summary]
86
87#### Architecture (4 issues)
88
89[Agent report summary]
90
91---
92
93### Debt Score Calculation
94

Starting Score: 100

• Critical Issues (5 x -10): -50 (capped at -40)
• High Issues (15 x -5): -75 (capped at -30)
• Medium Issues (27 x -2): -54 (capped at -20)
• Low Issues (17 x -1): -17 (capped at -10) = Final Score: 72/100 (Good)

**Score Interpretation:**
| Range | Rating | Action |
|-------|--------|--------|
| 90-100 | Excellent | Maintain |
| 75-89 | Good | Address critical issues |
| 60-74 | Needs Work | Prioritize debt reduction |
| 40-59 | Poor | Urgent attention needed |
| 0-39 | Critical | Stop feature work, fix debt |

---

### Recommendations

1. **Immediate** (this PR/sprint):
   - Fix CVE-2024-XXXXX by upgrading package X
   - Address P0 architecture issue in compiler.py

2. **Short-term** (next 2-4 sprints):
   - Increase test coverage on service.py
   - Refactor N+1 query patterns

3. **Long-term** (roadmap):
   - Establish complexity budgets
   - Implement automated debt tracking

---

### Trend Comparison (Full Audit Only)

**Previous Audit**: 2026-01-15
**Score Change**: 72 -> 72 (stable)

| Category | Previous | Current | Change |
|----------|----------|---------|--------|
| Complexity | 6 | 8 | +2 [up-arrow] |
| Dead Code | 5 | 3 | -2 [down-arrow] |
| Dependencies | 5 | 5 | 0 [right-arrow] |

**New Issues Since Last Audit**: 4
**Resolved Issues Since Last Audit**: 2

---

### Next Steps

- [ ] Address P0 issues before PR
- [ ] Schedule P1 issues for next sprint
- [ ] Re-run `/tech-debt-review` to verify fixes
- [ ] Run `/tech-debt-review --all` monthly for trend tracking

What This Review Checks

From Specialized Agents

What This Review Does NOT Check

• Linting/style: ruff handles this
• Type safety: mypy handles this
• Security: Aikido/bandit handle this (except dependency CVEs)
• Runtime bugs: Testing handles this

When to Use

Handoff

After completing this skill:

• Fix P0 issues: Address critical issues immediately
• Track P1 issues: Create Linear tickets for high-priority debt
• Continue workflow: Run /sw-verify before PR to validate all quality gates

References

• references/debt-taxonomy.md - Complete debt category definitions
• references/prioritization.md - Risk/impact/effort framework
• references/severity-criteria.md - Severity classification rules