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.