---
name: tech-debt
type: workflow
description: "Scans the codebase for technical debt indicators, categorizes and prioritizes findings, and maintains a debt register with repayment recommendations. Use when assessing codebase health, planning refactoring, or when the user mentions technical debt or code quality."
argument-hint: "[scan|add|prioritize|report]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write
context: fork
agent: technical-director
effort: 3
when_to_use: "Use when assessing codebase health, planning a refactoring sprint, or when the user mentions technical debt, code quality, cleanup, or wants to prioritize remediation work."
---
When this skill is invoked:
1. **Parse the subcommand** from the argument:
- `scan` — Scan the codebase for tech debt indicators
- `add` — Add a new tech debt entry manually
- `prioritize` — Re-prioritize the existing debt register
- `report` — Generate a summary report of current debt status
2. **For `scan`**:
- Search the codebase for debt indicators:
- `TODO` comments (count and categorize)
- `FIXME` comments (these are bugs disguised as debt)
- `HACK` comments (workarounds that need proper solutions)
- `@deprecated` markers
- Duplicated code blocks (similar patterns in multiple files)
- Files over 500 lines (potential god objects)
- Functions over 50 lines (potential complexity)
- Shallow wrappers or pass-through abstractions that fail the deletion test
- Categorize each finding:
- **Architecture Debt**: Wrong abstractions, missing patterns, coupling issues, shallow wrappers, failed deletion-test seams
- **Code Quality Debt**: Duplication, complexity, naming, missing types
- **Test Debt**: Missing tests, flaky tests, untested edge cases
- **Documentation Debt**: Missing docs, outdated docs, undocumented APIs
- **Dependency Debt**: Outdated packages, deprecated APIs, version conflicts
- **Performance Debt**: Known slow paths, unoptimized queries, memory issues
- Update the debt register at `docs/tech-debt-register.md`
For shallow-wrapper findings, apply this test before filing debt:
- If deleting the abstraction would mostly simplify the code and would not
force multiple callers to re-learn meaningful behavior, log it as
**Architecture Debt**.
- If deleting it would re-spread invariants, branching, retries, validation,
or ordering logic across callers, it is probably earning its keep; do not
file debt just because it is small.
Record shallow-wrapper debt explicitly in the description, for example:
- "Pass-through adapter around `OrderRepository` fails deletion test"
- "Thin mapper module mirrors caller complexity without adding leverage"
3. **For `add`**:
- Prompt for: description, category, affected files, estimated fix effort, impact if left unfixed
- Append to the debt register
4. **For `prioritize`**:
- Read the debt register
- Score each item by: `(impact_if_unfixed * frequency_of_encounter) / fix_effort`
- Re-sort the register by priority score
- Recommend which items to include in the next sprint
5. **For `report`**:
- Read the debt register
- Generate summary statistics:
- Total items by category
- Total estimated fix effort
- Items added vs resolved since last report
- Trending direction (growing / stable / shrinking)
- Flag any items that have been in the register for more than 3 sprints
- Output the report
### Debt Register Format
```markdown
## Technical Debt Register
Last updated: [Date]
Total items: [N] | Estimated total effort: [T-shirt sizes summed]
| ID | Category | Description | Files | Effort | Impact | Priority | Added | Sprint |
|----|----------|-------------|-------|--------|--------|----------|-------|--------|
| TD-001 | [Cat] | [Description] | [files] | [S/M/L/XL] | [Low/Med/High/Critical] | [Score] | [Date] | [Sprint to fix or "Backlog"] |
```
### Rules
- Tech debt is not inherently bad — it is a tool. The register tracks conscious decisions.
- Every debt entry must explain WHY it was accepted (deadline, prototype, missing info)
- "Scan" should run at least once per sprint to catch new debt
- Items older than 3 sprints without action should either be fixed or consciously accepted with a documented reason
- Do not file every small abstraction as debt. File only wrappers/modules that
are shallow enough to fail the deletion test.
## Protocol
- **Question**: Reads mode from argument (`scan` / `add` / `prioritize` / `report`); `add` mode prompts for debt details
- **Options**: Skip — mode drives execution path
- **Decision**: `add` mode — user provides description, category, effort estimate, and justification (why accepted)
- **Draft**: Changes shown in conversation before updating register
- **Approval**: "May I update `docs/technical/tech-debt.md`?"
## Output
Deliver exactly:
- **`scan`**: debt register updated at `docs/technical/tech-debt.md` + count of new items found by category
- **`add`**: new TD-[NNN] entry appended to register with effort, impact, and WHY it was accepted
- **`prioritize`**: ranked list of top 5 items by impact/effort score with recommended sprint to fix
- **`report`**: summary table — total items, effort distribution (S/M/L/XL), critical items count