tech-debt

Scan codebases for technical debt markers and prioritize a markdown debt register.

Updated Apr 10, 2026
One-click install
npx skills add https://github.com/emcconnell/nova-scout --skill tech-debt-emcconnell
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: tech-debt
Source: https://github.com/emcconnell/nova-scout/tree/main/.claude/skills/tech-debt
Command: npx skills add https://github.com/emcconnell/nova-scout --skill tech-debt-emcconnell

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Untracked technical debt accumulates as TODOs, hacks, large/complex files, duplicated code, deprecated APIs, and missing tests, making maintenance slow and risky. This Skill centralizes discovery, categorization, and tracking so teams can make conscious trade-offs and plan remediation work.

Core Features & Use Cases

  • Automated Scanning: Locate TODO, FIXME, HACK markers, @deprecated tags, large files (>500 lines), long functions (>50 lines), and duplicated code patterns.
  • Debt Register Management: Append new entries, add manual items with impact/effort metadata, and maintain a markdown register at docs/tech-debt-register.md.
  • Prioritization & Reporting: Score items by impact × frequency ÷ effort, re-sort the register for sprint planning, and generate read-only trend and category summary reports.
  • Use Case: Run a scan at the start of each sprint to capture new debt, then prioritize top items for the next sprint backlog.

Quick Start

Run the tech-debt skill with the scan subcommand to detect debt indicators and optionally append findings to docs/tech-debt-register.md.

Frequently Asked Questions about tech-debt

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I scan my codebase for technical debt automatically?

You can scan a codebase for technical debt by locating TODO, FIXME, and HACK markers, @deprecated tags, large files over 500 lines, long functions over 50 lines, and duplicated code patterns. The scan results can then be appended to a markdown debt register.

What is the best way to prioritize technical debt for sprint planning?

Technical debt prioritization is computed by scoring items based on impact multiplied by encounter frequency, then divided by estimated effort. This formula allows teams to re-sort the debt register and identify top items for the next sprint backlog.

Can I manually add technical debt items with impact and effort metadata?

Yes, manual technical debt items can be appended with custom impact and effort metadata. These entries are maintained alongside automated scan findings in a central markdown register located at docs/tech-debt-register.md.

Does this approach track deprecated APIs and duplicated code patterns?

Yes, tracking technical debt includes scanning for @deprecated tags and detecting duplicated code patterns. It also identifies large files, long functions, and standard markers like TODO and HACK to centralize discovery.

How do I generate a technical debt report for trend analysis?

Technical debt reporting generates read-only trend and category summary reports from the maintained markdown register. These reports summarize discovered debt categories to help teams make conscious trade-offs and plan remediation work.

What limitations exist when tracking technical debt in a markdown register?

The technical debt register is limited to a single markdown file at docs/tech-debt-register.md. It supports append, read, and write flows for debt entries but provides read-only reporting without integration into external issue tracking systems.