tech-debt-tracker

---
name: tech-debt-tracker
description: Use when scanning codebases for technical debt, scoring severity, tracking trends, or generating prioritized remediation plans for cleanup sprints and modernization.
category: Engineering
version: 1.0.0
tools: []
---

# Tech Debt Tracker

Comprehensive framework for identifying, analyzing, prioritizing, and tracking technical debt across codebases.

Tech debt is one of the most insidious challenges in software development. It compounds over time, slowing development velocity, increasing maintenance costs, and reducing code quality. Like financial debt, it accrues "interest" through increased development time, higher bug rates, and reduced team velocity.

Tech debt encompasses architectural shortcuts, missing tests, outdated dependencies, documentation gaps, and infrastructure compromises — not just messy code.

## What This Skill Provides

Three interconnected tools 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 data-driven decisions about tech debt, balancing new feature development with maintenance work.

## Quick Start — scan → prioritize → dashboard

All paths relative to skill folder.

### 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.

### 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
```

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 new snapshot, and assert targeted categories' counts dropped. A cleanup that doesn't move the dashboard is rework, not debt paydown.

## Technical Debt Classification Framework

Classify debt across categories: code complexity, testing gaps, documentation, architectural, dependency, infrastructure, and process.

## Common Pitfalls and How to Avoid Them

**Analysis Paralysis** → Set time limits for analysis, use "good enough" scoring

**Perfectionism** → Focus on high-impact debt; accept that some debt is manageable

**Ignoring Business Context** → Always tie debt work to business outcomes and customer impact

**Inconsistent Application** → Make debt tracking part of standard development workflow

**Tool Over-Engineering** → 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.