tech-debt-tracker
$
npx mdskill add alirezarezvani/claude-skills/tech-debt-tracker**Tier**: POWERFUL 🔥 **Category**: Engineering Process Automation **Expertise**: Code Quality, Technical Debt Management, Software Engineering
SKILL.md
.github/skills/tech-debt-trackerView on GitHub ↗
--- name: tech-debt-tracker description: 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. --- # 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: 1. **Debt Scanner** - Automatically identifies tech debt signals in your codebase 2. **Debt Prioritizer** - Analyzes and prioritizes debt items using cost-of-delay frameworks 3. **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 ```bash 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 ```bash 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: ```bash 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.
More from alirezarezvani/claude-skills
- a11y-auditAccessibility audit skill for scanning, fixing, and verifying WCAG 2.2 Level A and AA compliance across React, Next.js, Vue, Angular, Svelte, and plain HTML codebases. Use when auditing accessibility, fixing a11y violations, checking color contrast, generating compliance reports, or integrating accessibility checks into CI/CD pipelines.
- ab-test-setupWhen the user wants to plan, design, or implement an A/B test or experiment. Also use when the user mentions "A/B test," "split test," "experiment," "test this change," "variant copy," "multivariate test," "hypothesis," "conversion experiment," "statistical significance," or "test this." For tracking implementation, see analytics-tracking.
- ad-creativeWhen the user needs to generate, iterate, or scale ad creative for paid advertising. Use when they say 'write ad copy,' 'generate headlines,' 'create ad variations,' 'bulk creative,' 'iterate on ads,' 'ad copy validation,' 'RSA headlines,' 'Meta ad copy,' 'LinkedIn ad,' or 'creative testing.' This is pure creative production — distinct from paid-ads (campaign strategy). Use ad-creative when you need the copy, not the campaign plan.
- adversarial-reviewerAdversarial code review that breaks the self-review monoculture. Use when you want a genuinely critical review of recent changes, before merging a PR, or when you suspect Claude is being too agreeable about code quality. Forces perspective shifts through hostile reviewer personas that catch blind spots the author's mental model shares with the reviewer.
- aeoAnswer Engine Optimization (AEO) skill — optimize content to be cited by AI language models (ChatGPT, Perplexity, Claude, Gemini, Mistral) as authoritative sources. Distinct from SEO — AEO optimizes for citation in LLM-generated responses, not search rankings. Use when planning content for AI-first search audiences, auditing existing content for E-E-A-T signals, tracking which pages get cited by which LLMs, or building a citation-friendly content strategy. Triggers — 'AEO audit', 'optimize for ChatGPT', 'get cited by Perplexity', 'LLM citation strategy', 'answer engine optimization', 'content for AI search', 'E-E-A-T audit'. Output is a markdown audit report (default) or JSON for pipeline integration. Stdlib-only Python tools.
- agent-designerUse when the user asks to design a multi-agent system, pick an orchestration pattern (supervisor/swarm/pipeline), generate tool schemas for agents, or evaluate agent execution logs for cost, latency, and failure bottlenecks. Examples: 'design an agent architecture for research automation', 'generate Anthropic tool schemas from these tool descriptions', 'analyze these agent run logs for bottlenecks'. NOT for Claude Code workflow files (use workflow-builder) or single-agent prompt design (use agent-workflow-designer).
- agent-protocolInter-agent communication protocol for C-suite agent teams. Defines invocation syntax, loop prevention, isolation rules, and response formats. Use when C-suite agents need to query each other, coordinate cross-functional analysis, or run board meetings with multiple agent roles.
- agent-workflow-designerDesign production-grade multi-agent workflows with clear pattern choice (sequential, parallel, hierarchical), handoff contracts, failure handling, and cost/context controls. Use when architecting a multi-step agent pipeline, choosing between single-agent vs multi-agent approaches, or refactoring an LLM workflow that suffers from context bloat or unreliable handoffs.
- agenthubMulti-agent collaboration plugin that spawns N parallel subagents competing on the same task via git worktree isolation. Agents work independently, results are evaluated by metric or LLM judge, and the best branch is merged. Use when: user wants multiple approaches tried in parallel — code optimization, content variation, research exploration, or any task that benefits from parallel competition. Requires: a git repo.
- agile-product-ownerAgile product ownership for backlog management and sprint execution. Covers user story writing, acceptance criteria, sprint planning, and velocity tracking. Use when writing user stories, creating acceptance criteria, planning sprints, estimating story points, breaking down epics, or prioritizing the backlog.