---
name: technical-debt-assessment
description: >-
  Identifies, classifies, and prioritizes technical debt using interest-cost ROI
  analysis. Use when planning refactoring sprints, assessing codebase health,
  or deciding which debt to pay down first.
  NOT for architecture review, security audits, or greenfield design.
allowed-tools:
  - Read
  - Glob
  - Grep
  - Bash
---
## Identity & Scope
**Executor:** either  **Model tier:** sonnet
**Scope:** Source code, test suites, config files, build scripts, dependency manifests, documentation
**Off-limits:** Modifying code, running tests, deploying, making refactoring decisions (only recommend)
### Hard Rules
- No credentials in output or git — ever
- No spending money without explicit user approval
- No deleting files — archive first, 48hr hold
- No killing processes without explicit instruction
- Report completion to boss via structured output
## Essential Principles
1. **Quantify the interest, not just the debt** — Every item needs ongoing cost estimate (hrs/sprint wasted). Guards against: inventories that list everything but prioritize nothing.
2. **Prioritize by ROI, not annoyance** — Fix cost vs. interest saved. A 2hr fix saving 4hr/sprint beats a 40hr fix saving 5hr/sprint. Guards against: tackling the biggest debt instead of the most impactful.
3. **Classify the debt type** — Deliberate vs. inadvertent, prudent vs. reckless. Each needs different response. Guards against: treating all debt the same.
4. **Scan all surfaces** — Code, tests, infrastructure, docs, and dependencies all carry debt. Guards against: assessing only code while ignoring untested modules.
## When to Use
- Sprint planning to decide how much debt to pay down
- Pre-refactoring assessment for highest-ROI targets
- Quarterly codebase health reviews
- Evaluating refactor vs. rewrite decisions
- "How much tech debt do we have?" / "What should we refactor first?"
## When NOT to Use
- Full architecture review — use `code-architecture-review` instead
- Security vulnerability scanning — use security audit skills instead
- Designing new systems — use `system-design` instead
- Code-level bug hunting — use code review or testing skills instead
- Migration planning — use `migration-planning` instead
## Rationalizations to Reject
| Shortcut | Why it's wrong |
|----------|----------------|
| "I'll count TODO/FIXME comments as the inventory" | TODOs are hints, not systematic assessment — most debt is undocumented |
| "Old code is technical debt" | Stable, easy-to-modify code has zero interest regardless of age |
| "I'll skip test debt, we're looking at production code" | Missing tests are highest-interest debt — they multiply cost of every change |
| "I'll estimate fix costs without reading the code" | Accurate estimates require understanding dependencies and blast radius |
| "Everything is high priority" | If everything is high, nothing is — ROI ranking is mandatory |
## Workflow
### Phase 1: Debt Discovery
**Entry:** User has specified a codebase or component to assess
**Actions:**
1. Grep for debt indicators: TODO, FIXME, HACK, WORKAROUND, TEMPORARY, @deprecated
2. Glob for test files; compare against source to find untested modules
3. Read dependency manifests; identify outdated or deprecated dependencies
4. Check for duplication (similar file names, repeated patterns)
5. Identify config debt: hardcoded values, missing env handling, stale configs
6. Check doc freshness: README dates, stale comments, missing docs for key modules
**Exit:** Raw debt inventory with file locations and categories
### Phase 2: Classification and Quantification
**Entry:** Raw inventory exists
**Actions:**
1. Classify each item: deliberate/inadvertent x prudent/reckless
2. Estimate interest per item: hrs/sprint lost (bugs, slow dev, onboarding, deploy issues)
3. Estimate remediation cost: hrs to fix properly (read surrounding code for complexity)
4. Calculate ROI: interest saved per sprint / fix cost
5. Group by component to identify debt hotspots
**Exit:** Classified inventory with ROI scores
### Phase 3: Prioritization
**Entry:** Quantified inventory exists
**Actions:**
1. Rank all items by ROI (highest first)
2. Identify quick wins: fix cost under 4hrs with positive ROI
3. Identify strategic items: high ROI but multi-sprint effort
4. Identify foundational items: low individual ROI but blocking other improvements
5. Generate remediation plan: quick wins this sprint, strategic next quarter
**Exit:** Prioritized register with remediation recommendations
### Phase 4: Verification
**Entry:** All prior phases complete
**Actions:**
1. Verify every item has: category, component, interest cost, fix cost, ROI
2. Confirm all surfaces scanned (code, tests, config, docs, dependencies)
3. Check priorities justified by ROI, not subjective importance
4. Validate quick wins are genuinely under 4 hours
5. Ensure plan is actionable (specific items, not "reduce debt")
**Exit:** All checks pass — output results
## Output Format
```json
{
  "skill": "technical-debt-assessment",
  "status": "completed",
  "worker": "worker-id",
  "summary": "34 items across 8 components. 6 quick wins (save 18 hrs/sprint for 14 hrs work). Hotspot: auth module.",
  "findings": [
    {"item": "No tests for auth module (8 files, 1.2K LOC)", "severity": "critical", "detail": "Inadvertent/reckless. Interest: 8 hrs/sprint. Fix: 40 hrs. ROI: 0.2/sprint. Strategic."},
    {"item": "Hardcoded DB URL in 4 files", "severity": "high", "detail": "Deliberate/reckless. Interest: 2 hrs/sprint. Fix: 2 hrs. ROI: 1.0/sprint. Quick win."},
    {"item": "Deprecated axios 0.21 with CVE", "severity": "high", "detail": "Inadvertent/prudent. Interest: 1 hr/sprint. Fix: 3 hrs. ROI: 0.33/sprint. Quick win."}
  ],
  "debt_summary": {"total_items": 34, "quick_wins": 6, "strategic": 4, "foundational": 2, "low_priority": 22, "total_interest_per_sprint": "42 hours", "hotspot": "auth module"},
  "errors": [], "elapsed_seconds": 78.6
}
```
### Bad Example
```json
{"skill": "technical-debt-assessment", "summary": "Found tech debt", "findings": [{"item": "Code needs refactoring", "severity": "medium", "detail": "Several modules are messy"}]}
```
Wrong: No quantification, no ROI, vague descriptions, no file references, no prioritization.
## Escalation Triggers
STOP and report to boss (do NOT guess) when:
- [ ] Credentials or API keys hardcoded in codebase
- [ ] Dependency has critical CVE with no available patch
- [ ] Debt so severe a rewrite may be needed instead of refactoring
- [ ] Cannot estimate interest without bug tracking or sprint metrics
- [ ] Scope exceeds 100K LOC — needs focused sub-reviews
- [ ] Debt items pose active security or data integrity risks

Escalate as: `{"status": "escalated", "reason": "...", "context": "...", "recommendation": "..."}`
## Success Criteria
- [ ] All surfaces scanned: code, tests, config, docs, dependencies
- [ ] Every item has: classification, component, interest cost, fix cost, ROI
- [ ] Items ranked by ROI with quick wins identified
- [ ] Hotspots (highest debt concentration) called out
- [ ] Remediation plan separates quick wins, strategic, foundational
- [ ] Output matches the JSON format above
- [ ] No escalation triggers hit (or all reported)
