tech-debt-discovery

type	skill
lifecycle	stable
inheritance	inheritable
name	tech-debt-discovery
description	Systematic technical debt inventory and prioritization. Use when asked to "find tech debt", "show me the TODOs", "how healthy is this codebase", "what should we fix first", "find code smells", "audit code quality", or "identify hotspots". Scans code markers, analyzes git history, checks dependencies, and produces a prioritized debt report.
applyTo	**/*debt*,**/*TODO*,**/*FIXME*,**/*smell*
tier	standard
currency	2026-04-22T00:00:00.000Z

Tech Debt Discovery

Systematically discover, inventory, and prioritize technical debt. Produces actionable reports.

When to Use

• Assessing codebase health or planning a cleanup sprint
• User asks to "find tech debt", "audit the code", or "what needs fixing"
• Before a major feature to identify risky areas

What This Skill Is NOT

• Not refactor: Refactoring fixes debt. This skill finds and inventories it.

---

Process

Step 1: Code Marker Scan

Search for explicit debt markers left by developers:

Marker	Severity
FIXME, HACK, XXX	High
TODO, TEMPORARY, WORKAROUND	Medium
DEPRECATED (in comments)	Medium
NOTE, NB	Low

For each marker found, capture: file path, line number, surrounding context (±5 lines), age via git blame, author.

Step 2: Dependency Analysis

Detect the project's dependency files by scanning the repo, then:

1. List all dependencies with current vs. latest versions
2. Flag known vulnerabilities (if security advisories are accessible)
3. Identify abandoned dependencies (no updates in 2+ years)
4. Check for duplicate dependencies (same purpose, different packages)

Finding	Severity
Known vulnerability	Critical
Major version behind (2+ majors)	High
Abandoned dependency	High
Minor version behind	Medium
Duplicates	Low

Step 3: Git History Analysis

Use git history to find code hotspots — files that change frequently often harbor complexity:

• Churn: most frequently changed files in recent history
• : files touched by most authors