SKILL · coding
Technical Debt Triage
Systematic framework for assessing, categorizing, and prioritizing technical debt. Produces a debt inventory with impact scores, remediation cost estimates, and a prioritized action plan. Turns vague "we should refactor this" into concrete decisions: what to fix, what to live with, what to schedule, and what to delete.
Requires
Install as Claude Code skill
Drop into ~/.claude/skills/<name>/SKILL.md
Technical Debt Triage
What This Skill Does
Turns vague "we should refactor this" feelings into concrete, prioritized decisions. Produces a technical debt inventory with impact analysis and a clear action plan.
The skill answers three questions:
- What debt do we actually have? (inventory)
- Which debt is hurting us most? (prioritization)
- What should we do about it? (action plan)
Debt Categories
| Category | Description | Example |
|---|---|---|
| Architecture | Structural decisions that limit the system | Monolith that should be services |
| Design | Code organization and pattern violations | God class, circular dependencies |
| Code Quality | Readability, duplication, complexity | 2000-line file, copy-paste logic |
| Testing | Missing or inadequate test coverage | No integration tests, flaky tests |
| Infrastructure | Outdated deps, missing automation | 3-year-old framework version |
| Documentation | Missing or stale docs | README from initial commit |
| Security | Known vulnerabilities not yet addressed | Deprecated auth library |
Impact Scoring Matrix
Each debt item gets two scores (1-5):
Pain Score — How much is this hurting us today?
- 5: Blocking feature work, causing incidents
- 4: Slowing every sprint significantly
- 3: Causes regular friction
- 2: Annoying but workaround exists
- 1: Theoretical concern, no current pain
Risk Score — How dangerous is leaving this?
- 5: Security vulnerability or data loss risk
- 4: System stability at risk under load
- 3: Will become critical within 3 months
- 2: Will become painful within 6 months
- 1: Low risk, long time horizon
Priority = Pain x Risk (1-25 scale)
Remediation Cost Estimation
For each item, estimate:
- T-shirt size: XS (hours) | S (1-2 days) | M (3-5 days) | L (1-2 weeks) | XL (sprint+)
- Risk of remediation: How likely is this fix to introduce new problems?
- Dependencies: What else needs to change?
Action Categories
Based on priority vs. cost:
| Low Cost | High Cost | |
|---|---|---|
| High Priority | Fix Now — quick wins that reduce pain | Schedule — plan a dedicated sprint |
| Low Priority | Opportunistic — fix when touching that code | Accept — document and move on |
Plus one special category:
- Delete — code/features nobody uses. Best refactoring is deletion.
Process
- Inventory — scan the codebase, collect known debt items from the team
- Categorize — assign each item to a debt category
- Score — rate pain and risk for each item
- Estimate — t-shirt size the remediation effort
- Prioritize — sort by priority score, group into action categories
- Plan — produce a concrete timeline: what this sprint, next sprint, this quarter
Output Format
## Technical Debt Triage: {project name}
### Debt Inventory
| # | Item | Category | Pain | Risk | Priority | Cost | Action |
|---|------|----------|------|------|----------|------|--------|
| 1 | ... | Architecture | 5 | 4 | 20 | L | Schedule |
| 2 | ... | Security | 3 | 5 | 15 | S | Fix Now |
### Fix Now (this sprint)
- Item 2: {description + specific fix approach}
### Schedule (dedicated effort)
- Item 1: {description + scope + suggested timeline}
### Opportunistic (when touching that code)
- ...
### Accept (document and move on)
- ...
### Delete candidates
- ...
Anti-Patterns
- Listing debt without scoring it (everything feels equally important)
- Treating all debt as equal priority
- Refactoring without measuring impact
- Perfectionism — some debt is fine to live with
- Ignoring the "delete" option — unused code is the worst debt