tech-debt— agent skill

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

1. 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)
• Categorize each finding:
• Architecture Debt: Wrong abstractions, missing patterns, coupling issues
• 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

1. For `add`:

• Prompt for: description, category, affected files, estimated fix effort, impact if left unfixed
• Append to the debt register

1. 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

1. 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

## 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