About

Imported from terminalskills/skills (skills/tech-debt-analyzer/SKILL.md). Install upstream with npx skills add terminalskills/skills --skill tech-debt-analyzer. Copyright stays with the author (Apache-2.0).

Technical Debt Analyzer

Name: tech-debt-analyzer
Author: terminalskills

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

Use it

Copy one of these into your project. Installing also returns the manifest and these snippets.

yaml

targets:
  - https://api.opensmartroute.ai/api/v1/registry/terminalskills-skills-tech-debt-analyzer/manifest   # or paste the manifest below

Manifest

An Open Capability Manifest: the router reads it to know what this does, what it costs and when to pick it.

terminalskills-skills-tech-debt-analyzer.ocm.jsonjson

{
  "ocm": "1",
  "id": "terminalskills-skills-tech-debt-analyzer",
  "kind": "skill",
  "name": "tech-debt-analyzer",
  "description": "Scans codebases for technical debt signals and prioritizes them by business impact. Finds TODO/FIXME/HACK comments, outdated dependencies, code duplication, and correlates with git history to identify high-churn debt hotspots. Use when someone asks about technical debt, code quality audit, refactoring priorities, or maintainability assessment. Trigger words: tech debt, code quality, refactoring, TODOs, maintainability, code health.",
  "publisher": "terminalskills",
  "version": "1.0.0",
  "capabilities": {
    "domains": [
      "coding"
    ],
    "tags": [
      "skill-md",
      "technical-debt",
      "code-quality",
      "refactoring",
      "engineering",
      "skills-sh"
    ],
    "languages": [
      "en"
    ]
  },
  "quality_prior": 0.6,
  "examples": [
    "Scans codebases for technical debt signals and prioritizes them by business impact. Finds TODO/FIXME/HACK comments, outdated dependencies, code duplication, and correlates with git history to identify high-churn debt hotspots. Use when someone asks about technical debt, code quality audit, refactoring priorities, or maintainability assessment. Trigger words: tech debt, code quality, refactoring, TODOs, maintainability, code health."
  ],
  "primary": false,
  "metadata": {
    "source": {
      "provider": "skills.sh",
      "repository": "https://github.com/terminalskills/skills",
      "path": "skills/tech-debt-analyzer/SKILL.md",
      "ref": "HEAD",
      "url": "https://github.com/terminalskills/skills/blob/HEAD/skills/tech-debt-analyzer/SKILL.md",
      "key": "terminalskills/skills/skills/tech-debt-analyzer/SKILL.md"
    },
    "compatibility": "Requires git repository with history; supports any language",
    "license": "Apache-2.0"
  },
  "instructions": "# Technical Debt Analyzer\n\n## Overview\n\nThis 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.\n\n## Instructions\n\n### Step 1: Gather Debt Signals\n\nScan the codebase for these indicators:\n\n```bash\n# TODO/FIXME/HACK markers with context\ngrep -rn \"TODO\\|FIXME\\|HACK\\|XXX\\|WORKAROUND\" --include=\"*.ts\" --include=\"*.js\" --include=\"*.py\" --include=\"*.go\" --incl",
  "cost": {
    "context_tokens": 1158
  }
}

Fetch it by URL: GET /api/v1/registry/terminalskills-skills-tech-debt-analyzer/manifest?version=1.0.0

Reviews

Star ratings from people who tried it. One review per account; edit yours any time.

No reviews yet. Install it, try it, and be the first to rate it.