Tech Debt Hotspot Register
Rank tech debt by evidence (git churn x complexity x tests x bug history) into a register with cost, size, and pay-now-or-defer calls.
Before & after
Same prompt, same agent — the only difference is the skill.
Tackling tech debt can feel overwhelming. Here's a general approach: - Inventory the debt — list the problem areas - Prioritize by impact and effort - Focus on debt that slows you down most - Fix incrementally alongside feature work - Prevent new debt with better practices It helps to distinguish debt that actively hurts you from debt that's just ugly but harmless. Focus your energy on the former. Would you like help creating a plan?
Tech debt, worked as a repeatable pass instead of a vibe. "The whole codebase" is not actionable; this makes it a ranked, sized list. STEP 1 — INVENTORY, BY TYPE (not one bucket) ROT — dead code, unused deps, stale config FRICTION — the files everyone dreads touching (ask the team; they know) RISK — no tests on critical paths, security shortcuts DESIGN — the abstraction that fights every new feature STEP 2 — SCORE EACH: PAIN x FREQUENCY The key move. A gnarly module nobody touches is low priority; a mildly-annoying one edited weekly is high. Debt cost = how bad x how often you hit it. This ranking is what stops you from gold-plating a dead corner while the daily-friction file festers. STEP 3 — SEPARATE "HURTS" FROM "UGLY" Ugly-but-stable code that's rarely touched: leave it. Debt only counts if it's slowing you down or risking an incident. Half of most "tech debt" is just aesthetic and safe to ignore. STEP 4 — THE PLAN Top 3 by score → scheduled, sized, owned. The rest → a "boy scout" rule (fix debt in files you're already editing), so it drains without a dedicated project. STEP 5 — STOP THE BLEEDING One prevention change (a lint rule, a review gate) so the same debt class doesn't refill behind you. WHAT NOT TO DO A three-month "pay down all debt" project. It stops feature work, and the low-frequency items you'd fix weren't costing anything. Rank, fix the top 3, boy-scout the rest. Point me at the repo or name the files people dread, and I'll build the ranked list.
About this skill
Ugly code nobody touches is cheap debt; code that changes weekly with no tests is expensive. This skill ranks debt by evidence from your repo and turns it into a register engineers can act on and leadership can fund.
What it does
- Runs git churn, bug-fix concentration, and ownership analysis to find hotspots
- Crosses churn with complexity, test coverage, and outdated or end-of-life dependencies
- Records each item with a file path, its current cost to the team, fix size, and trigger
- Decides pay now, pay with the next change, or defer, with incremental paths instead of rewrites
- Separates real debt from style preferences and flags security risks on their own
What you get
A debt register with top hotspots, risk items, a leave-alone list, a paydown plan, and an optional three-sentence summary for leadership.
Best for
Tech leads and engineering managers deciding where refactoring time pays off, or justifying it to leadership.
SKILL.md preview
---
name: tech-debt
description: Find, rank, and plan paydown of technical debt using evidence from the repo - change frequency (churn) crossed with complexity and test coverage, incident and bug history, and outdated or end-of-life dependencies - producing a debt register where every item has a file reference, its "interest" (what it costs the team now), a fix size, and a pay-now or defer call. Use when the user says "what's our tech debt?", "where should we refactor first?", "is this module worth cleaning up?", "make a tech debt backlog", "justify refactoring time to leadership", or casually "this code is a mess, where do I start?" or "should we fix this before the new feature?".
---
… (sign up to view the full skill)More development skills
View all Development skills →Performance Bottleneck Profiling: Node, Python, Go
Classifies a slowdown, gives exact profiler commands, reads the output, and proves the fix with same-conditions p95/p99 numbers.
Feature Scaffolding with Working Tests
Turn a short feature spec into code, runnable tests, and integration wiring that match your existing project.
Feature Flag Rollouts and Kill Switches
Design staged flag rollouts, verify rollback paths, and audit flag debt with explicit defaults, gates, and retirement plans.
Microcontroller Firmware and RTOS Engineering
Build and debug MCU firmware with bounded ISR/RTOS timing, safe DMA ownership, and measured power budgets.