Tech Debt Tracker

Tech Debt Tracker is an AI skill that identifies, categorizes, and prioritizes technical debt in software projects to guide remediation efforts. It covers code quality scanning, dependency staleness detection, architecture erosion analysis, debt impact assessment, and remediation planning that transform vague complaints about code quality into actionable improvement plans.

What Is This?

Overview

Tech Debt Tracker provides systematic approaches for finding and managing technical debt across a codebase. It addresses code complexity analysis using metrics like cyclomatic complexity and cognitive complexity, dependency staleness detection showing which packages are outdated and by how much, architecture pattern violations where code has drifted from intended design, test coverage gaps in critical code paths, documentation debt where code has outgrown its documentation, and debt prioritization based on business impact and remediation cost.

Who Should Use This

This skill serves engineering managers planning technical debt sprints, architects assessing codebase health across projects, developers advocating for refactoring time with concrete evidence, and teams balancing feature delivery with maintenance work.

Why Use It?

Problems It Solves

Technical debt accumulates invisibly until it significantly slows development. Teams argue about what constitutes debt and what to fix first without objective data. Management approves debt remediation reluctantly because the impact is hard to quantify. Without tracking, resolved debt items are replaced by new ones at the same rate.

Core Highlights

The skill quantifies debt with concrete metrics rather than subjective assessments. Prioritization considers both the cost of the debt (developer time lost) and the cost of remediation. Trend tracking shows whether debt is increasing or decreasing over time. Remediation plans break large improvements into manageable increments.

How to Use It?

Basic Usage

class TechDebtScanner:
    def __init__(self, project_path):
        self.path = project_path
        self.debt_items = []

    def scan_complexity(self, threshold=15):
        for filepath in self.find_source_files():
            metrics = self.analyze_complexity(filepath)
            for func in metrics["functions"]:
                if func["cyclomatic_complexity"] > threshold:
                    self.debt_items.append({
                        "type": "complexity",
                        "file": filepath,
                        "function": func["name"],
                        "score": func["cyclomatic_complexity"],
                        "impact": "Difficult to test and modify"
                    })

    def scan_dependencies(self):
        outdated = self.get_outdated_packages()
        for pkg in outdated:
            major_behind = pkg["latest_major"] - pkg["current_major"]
            self.debt_items.append({
                "type": "dependency",
                "package": pkg["name"],
                "current": pkg["current"],
                "latest": pkg["latest"],
                "severity": "high" if major_behind >= 2 else "medium"
            })

Real-World Examples

Technical Debt Report
Project: user-service
Scan Date: 2024-03-15

Debt Summary:
  Total items: 47
  Critical: 3 | High: 12 | Medium: 22 | Low: 10

Top Priority Items:
1. [CRITICAL] auth_handler.py: Cyclomatic complexity 42
   Impact: Causes 60% of bugs in auth module
   Remediation: Split into 4 focused functions (est: 2 days)

2. [CRITICAL] Dependency: django 3.2 (EOL)
   Impact: No security patches since April 2024
   Remediation: Upgrade to Django 5.0 (est: 5 days)

3. [HIGH] No test coverage for payment processing
   Impact: Payment bugs found only in production
   Remediation: Add integration test suite (est: 3 days)

Trend: Debt increased 15% since last scan (3 months ago)
  New items: 12 | Resolved: 5 | Net change: +7

Advanced Tips

Integrate debt scanning into CI so every PR shows whether it increases or decreases the debt score. Create a debt budget that allows a controlled amount of debt to accumulate before requiring remediation. Link debt items to the engineering time they cost so you can calculate ROI for remediation sprints.

When to Use It?

Use Cases

Use Tech Debt Tracker when planning dedicated technical debt reduction sprints, when justifying refactoring time to stakeholders with quantified evidence, when onboarding to a project and needing to understand codebase health, or when establishing quality standards that include debt tracking metrics.

Related Topics

Static analysis tools like SonarQube, code quality metrics, dependency management, refactoring practices, and engineering health scorecards all complement tech debt tracking.

Important Notes

Requirements

Static analysis tooling for the project's programming languages. A dependency management system that can report outdated packages. Historical data for tracking debt trends over time.

Usage Recommendations

Do: prioritize debt items based on their impact on developer productivity and system reliability. Track debt metrics over time to measure improvement. Include debt reduction targets in sprint planning alongside feature work.

Don't: attempt to eliminate all technical debt at once, as this stalls feature delivery. Use debt metrics as individual performance indicators, as this discourages honest reporting. Ignore low-severity debt indefinitely, as it accumulates into larger problems.

Limitations

Automated scanners detect structural debt like complexity and staleness but cannot assess design-level debt that requires human judgment. Debt prioritization depends on business context that scanning tools do not understand. Metrics can misrepresent code health when high complexity is genuinely necessary for a problem domain.