tech-debt-analyzer

Getting Started

1. Install the skill using the command above
2. Open your AI coding agent (Claude Code, Codex, Gemini CLI, or Cursor)
3. Reference the skill in your prompt
4. The AI will use the skill's capabilities automatically

Example Prompts

• "Review the open pull requests and summarize what needs attention"
• "Generate a changelog from the last 20 commits on the main branch"

Overview

This skill identifies and prioritizes technical debt by combining static code analysis with git history. Instead of just finding code smells, it answers the critical question: "Which debt is actually hurting us?" by correlating complexity with change frequency, bug density, and developer contention.

Instructions

Step 1: Gather Debt Signals

Scan the codebase for these indicators:

# TODO/FIXME/HACK markers with context
grep -rn "TODO\|FIXME\|HACK\|XXX\|WORKAROUND" --include="*.ts" --include="*.js" --include="*.py" --include="*.go" --include="*.java" src/

# Long functions (proxy: count lines between function declarations)
# Outdated dependencies
npm outdated 2>/dev/null || pip list --outdated 2>/dev/null || go list -m -u all 2>/dev/null

Step 2: Measure Complexity

For each file, estimate cyclomatic complexity:

• Count branching statements (if, else, switch cases, ternary, catch, &&, ||)
• Flag functions with complexity > 15 as high
• Flag files with average complexity > 10 as concerning

Step 3: Analyze Git History

# Change frequency per file (last 6 months)
git log --since="6 months ago" --pretty=format: --name-only | sort | uniq -c | sort -rn | head -30

# Bug-fix correlation (commits mentioning fix/bug/hotfix)
git log --since="6 months ago" --grep="fix\|bug\|hotfix" --pretty=format: --name-only | sort | uniq -c | sort -rn | head -20

# Developer contention (unique authors per file)
git log --since="3 months ago" --pretty=format:"%an" -- <file> | sort -u | wc -l

Step 4: Score and Prioritize

Calculate a composite score (0-10) for each debt item:

• Change frequency (30%): How often the file is modified
• Bug density (30%): How many bug-fix commits reference this file
• Developer contention (20%): How many developers work on it weekly
• Complexity score (20%): Normalized cyclomatic complexity

Classify into:

• P0: Score ≥ 8 — Fix this sprint, it's actively causing pain
• P1: Score 5-7.9 — Schedule within the quarter
• P2: Score < 5 — Monitor but don't prioritize

Step 5: Generate Remediation Tickets

For P0 and P1 items, produce structured tickets with:

• Problem description with specific metrics
• Acceptance criteria (measurable)
• Suggested refactoring approach
• Estimated effort in story points (1-13 scale)
• Risk assessment

Examples

Example 1: Monorepo Scan

User prompt:

Analyze our Python Django project for tech debt priorities

Agent output:

Tech Debt Analysis — myproject/ (156 files, 22,400 LOC)

P0 — Fix This Sprint
  views/checkout.py     Score: 9.1  Complexity: 38  Churn: 24/mo  Bugs: 9
    → 340-line process_order() handles payment, inventory, email, logging
    → Recommendation: Extract into OrderProcessor, PaymentHandler, NotificationService

P1 — This Quarter
  models/user.py        Score: 6.8  Complexity: 22  Churn: 12/mo  Bugs: 4
    → User model has 28 methods, some unrelated to user domain
    → Recommendation: Extract ProfileMixin, PreferencesMixin

P2 — Monitor
  utils/legacy_xml.py   Score: 1.3  Complexity: 31  Churn: 0/mo   Bugs: 0
    → Complex but completely stable. Do not refactor.

Debt trend indicator: 📈 Growing (+3 files above threshold vs 3 months ago)

Example 2: Dependency Audit

User prompt:

Check for outdated and risky dependencies in our Node.js project

Agent output:

Dependency Debt Report
──────────────────────

CRITICAL (security + major version behind)
  lodash          4.17.15 → 4.17.21    3 known vulnerabilities
  express         4.17.1  → 4.21.2     1 moderate CVE

MAJOR VERSION BEHIND
  typescript      4.9.5   → 5.7.3      Breaking changes in 5.x
  jest            27.5.1  → 29.7.0     Migration guide available

MINOR UPDATES (low risk)
  axios           1.6.0   → 1.7.9
  dotenv          16.3.1  → 16.4.7

Recommendation: Address critical items immediately (1-2 hours).
Schedule TypeScript 5.x migration as a dedicated sprint task (2-3 days).

Guidelines

• Business impact over code purity — a complex file that never changes and never breaks is NOT high priority debt
• Data over opinions — always back prioritization with git metrics, not gut feeling
• Don't recommend rewriting stable legacy code — if it works and nobody touches it, leave it alone
• Include effort estimates — debt without remediation cost is not actionable
• Track trends — a single snapshot is useful; comparing snapshots over time is powerful
• Respect team context — note when refactoring requires domain knowledge or coordination across teams