tech-debt-tracker
Scan codebases for technical debt, score severity, track trends, and generate prioritized remediation plans. Use when users mention tech debt, code quality, refactoring priority, debt scoring, cleanup sprints, or code health assessment. Also use for legacy code modernization planning and maintenance cost estimation.
- Installs
- 616
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/alirezarezvani/claude-skills --skill tech-debt-tracker- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads tech-debt-tracker automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
Tech Debt Tracker
Tier: POWERFUL 🔥
Category: Engineering Process Automation
Expertise: Code Quality, Technical Debt Management, Software Engineering
Overview
Tech debt is one of the most insidious challenges in software development - it compounds over time, slowing down development velocity, increasing maintenance costs, and reducing code quality. This skill provides a comprehensive framework for identifying, analyzing, prioritizing, and tracking technical debt across codebases.
Tech debt isn't just about messy code - it encompasses architectural shortcuts, missing tests, outdated dependencies, documentation gaps, and infrastructure compromises. Like financial debt, it accrues "interest" through increased development time, higher bug rates, and reduced team velocity.
What This Skill Provides
This skill offers three interconnected tools that form a complete tech debt management system:
- Debt Scanner - Automatically identifies tech debt signals in your codebase
- Debt Prioritizer - Analyzes and prioritizes debt items using cost-of-delay frameworks
- Debt Dashboard - Tracks debt trends over time and provides executive reporting
Together, these tools enable engineering teams to make data-driven decisions about tech debt, balancing new feature development with maintenance work.
Quick Start — scan → prioritize → dashboard
All paths relative to this skill folder. The scanner's JSON output feeds the prioritizer directly; dated inventory snapshots feed the dashboard.
1. Scan the codebase
python3 scripts/debt_scanner.py /path/to/codebase --format json --output debt_inventory.json
Emits debt_inventory.json with scan_metadata, summary, debt_items[], file_statistics, and recommendations. Report the summary counts to the user. (Dry run: assets/sample_codebase.)
2. Prioritize the backlog
python3 scripts/debt_prioritizer.py debt_inventory.json --framework wsjf --team-size 6 --sprint-capacity 20 --format json --output debt_priorities.json
Frameworks: cost_of_delay (default), wsjf, rice. Output contains prioritized_backlog (work top-down), sprint_allocation (paste into sprint planning), and insights.
3. Track trends over time
Keep dated snapshots (debt_YYYY-MM-DD.json), then:
python3 scripts/debt_dashboard.py --input-dir snapshots/ --period monthly --format both --output debt_dashboard
Or pass files explicitly (samples: assets/historical_debt_2024-01-15.json assets/historical_debt_2024-02-01.json). The dashboard reports trend direction and executive-ready summaries — use it to verify a cleanup sprint actually reduced debt.
Verification loop
After a remediation sprint: re-run step 1, re-run step 3 with the new snapshot, and assert the targeted categories' counts dropped. A cleanup that doesn't move the dashboard is rework, not debt paydown.
Technical Debt Classification Framework
→ See references/debt-frameworks.md for details (also: references/debt-classification-taxonomy.md, references/prioritization-framework.md, references/stakeholder-communication-templates.md)
Common Pitfalls and How to Avoid Them
1. Analysis Paralysis
Problem: Spending too much time analyzing debt instead of fixing it. Solution: Set time limits for analysis, use "good enough" scoring for most items.
2. Perfectionism
Problem: Trying to eliminate all debt instead of managing it. Solution: Focus on high-impact debt, accept that some debt is acceptable.
3. Ignoring Business Context
Problem: Prioritizing technical elegance over business value. Solution: Always tie debt work to business outcomes and customer impact.
4. Inconsistent Application
Problem: Some teams adopt practices while others ignore them. Solution: Make debt tracking part of standard development workflow.
5. Tool Over-Engineering
Problem: Building complex debt management systems that nobody uses. Solution: Start simple, iterate based on actual usage patterns.
Technical debt management is not just about writing better code - it's about creating sustainable development practices that balance short-term delivery pressure with long-term system health. Use these tools and frameworks to make informed decisions about when and how to invest in debt reduction.
FAQ
What does the tech-debt-tracker skill do?
Scan codebases for technical debt, score severity, track trends, and generate prioritized remediation plans. Use when users mention tech debt, code quality, refactoring priority, debt scoring, cleanup sprints, or code health assessment. Also use for legacy code modernization planning and maintenance cost estimation.
How do I install tech-debt-tracker?
Run npx skills add https://github.com/alirezarezvani/claude-skills --skill tech-debt-tracker in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/tech-debt-tracker/ (personal) or .claude/skills/tech-debt-tracker/ (project).
Which AI agents can use tech-debt-tracker?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is tech-debt-tracker safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains tech-debt-tracker?
It is published by alirezarezvani in alirezarezvani/claude-skills. It has 616 recorded installs.
More from alirezarezvani/claude-skills
engineering-skills
alirezarezvani/claude-skills
Index of the engineering-team skills bundle for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw, and 6 more tools. Architecture, frontend, backend, QA, DevOps, security, AI/ML, data engineering, Playwright, Stripe, AWS, MS365 (stdlib-only Python tools). Use when browsing or choosing among engineering-team role skills — load only the one specialist SKILL.md you need, never bulk-load the bundle.
finance-skills
alirezarezvani/claude-skills
Router/index for the finance skills bundled in this plugin: financial-analyst (ratio analysis, DCF valuation, budget variance, rolling forecasts), saas-metrics-coach (ARR/MRR, churn, CAC/LTV, NRR, quick ratio) and month-end-close (close calendar, reconciliations, flux review). Use when a finance request doesn't obviously match one skill and you need to pick the right one (e.g., 'analyze these financials', 'how healthy are my SaaS metrics').
marketing-skills
alirezarezvani/claude-skills
Directory and router for the marketing skills library. Use when you need to find the right marketing skill for a task, see what marketing capabilities exist, or get oriented in this plugin. 44 specialist skills across 8 pods (content, SEO + AEO, CRO, channels, growth, intelligence, sales enablement, ops), 59 stdlib Python tools. Routes to one skill — it does not execute marketing work itself.
business-growth-skills
alirezarezvani/claude-skills
Router/index for the 4 business & growth skills bundled in this plugin: customer-success-manager (health scoring, churn risk, expansion), sales-engineer (RFP analysis, competitive matrices, PoC planning), revenue-operations (pipeline, forecast accuracy, GTM efficiency), and contract-and-proposal-writer. Use when a growth/revenue request doesn't obviously match one skill and you need to pick the right one (e.g., 'which accounts are at risk', 'should we bid on this RFP').
engineering-advanced-skills
alirezarezvani/claude-skills
Index of 37 advanced engineering agent skills for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw. Use when browsing or choosing among the POWERFUL-tier engineering skills: agent design, RAG, MCP servers, CI/CD, database design, observability, security auditing, changelog/release automation, reliability (SLO/chaos/flags/operators), platform ops.
product-skills
alirezarezvani/claude-skills
Use when coordinating product work across the 12 bundled product sub-skills (RICE, OKRs, UX research, design tokens, competitive teardown, analytics, experiments, discovery, roadmaps, spec-to-repo, landing pages, SaaS scaffolding) or the 4 standalone product-team plugins (user stories, Apple HIG, code-to-PRD, research summarizer). Triggers on 'help me prioritize', 'plan a product experiment', 'we ship features nobody uses', 'run the discovery loop', 'is our OST sound'. Forks context to route to one sub-skill via a deterministic signal router and returns a digest; can also drive a continuous-discovery loop (Torres cadence tracker + OST linter as machine gates) or a full goal→plan→execute→verify→close run through the repo-wide agent-harness. Distinct from project-management (how to deliver vs what to build), marketing/landing (from-scratch pages), and engineering/agent-harness (the generic loop engine this orchestrator plugs into).
Popular code quality & workflow skills
grill-me
mattpocock/skills
A relentless interview to sharpen a plan or design.
improve-codebase-architecture
mattpocock/skills
Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
handoff
mattpocock/skills
Compact the current conversation into a handoff document for another agent to pick up.
domain-modeling
mattpocock/skills
Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.
codebase-design
mattpocock/skills
Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
diagnosing-bugs
mattpocock/skills
Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.