When this skill is invoked:

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

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

For add :

• Prompt for: description, category, affected files, estimated fix effort, impact if left unfixed

• Append to the debt register

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

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]

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