Technical Debt Analyzer

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