# Tracking and Prioritizing Technical Debt with Claude Skills' Tech-Debt-Tracker

> Efficiently track and prioritize technical debt with Claude Skills' Tech-Debt-Tracker. Discover, rank, and monitor code issues using interest-rate calculations and WSJF scoring.

- Repository: [Alireza Rezvani/claude-skills](https://github.com/alirezarezvani/claude-skills)
- Tags: how-to-guide
- Published: 2026-03-09

---

**The Tech-Debt-Tracker skill provides a three-step workflow—scanning, prioritizing, and dashboard visualization—to discover, rank, and monitor technical debt across any codebase using interest-rate calculations and WSJF scoring.**

Engineering teams struggling with accumulated technical debt can leverage the **Tech-Debt-Tracker** from the `alirezarezvani/claude-skills` repository. This POWERFUL tier skill in the Engineering domain offers a language-agnostic, data-driven approach to **tracking and prioritizing technical debt** through automated detection and economic scoring models.

## The Three-Step Architecture for Tracking and Prioritizing Technical Debt

The Tech-Debt-Tracker implements a modular pipeline consisting of three core components that transform raw code analysis into executive-ready reports.

### Step 1: Debt Discovery with the Scanner

The **Debt Scanner** ([`engineering/tech-debt-tracker/scripts/debt_scanner.py`](https://github.com/alirezarezvani/claude-skills/blob/main/engineering/tech-debt-tracker/scripts/debt_scanner.py)) traverses the file tree to identify technical debt signals. For Python files, it utilizes Abstract Syntax Tree (AST) parsing, while other languages rely on configurable regex patterns. The scanner emits a detailed JSON inventory containing debt items with their type, severity, file location, and metadata.

The scanner loads default thresholds via `_load_default_config()`, which can be overridden using the `--config` flag to point to a custom JSON configuration file.

### Step 2: Intelligent Prioritization with Interest-Rate Scoring

The **Debt Prioritizer** ([`engineering/tech-debt-tracker/scripts/debt_prioritizer.py`](https://github.com/alirezarezvani/claude-skills/blob/main/engineering/tech-debt-tracker/scripts/debt_prioritizer.py)) consumes the scanner's JSON output and applies economic models to assign business value to each debt item. It calculates an **interest rate** using the formula:

```

Interest Rate = Impact × Frequency / Time

```

The prioritizer then computes **Cost-of-Delay** as:

```

Cost-of-Delay = Interest × Time Until Fix × TeamSizeMultiplier

```

Using WSJF-style scoring, each item receives a `priority_score` and categorical priority assignment (`critical`, `high`, `medium`, or `low`), enabling data-driven backlog refinement.

### Step 3: Executive Reporting via the Dashboard

The **Debt Dashboard** ([`engineering/tech-debt-tracker/scripts/debt_dashboard.py`](https://github.com/alirezarezvani/claude-skills/blob/main/engineering/tech-debt-tracker/scripts/debt_dashboard.py)) aggregates historical scan data to produce visual reports. It calculates a **health score** for the codebase:

```

Health Score = 100 – (debt_density × 10)

```

The dashboard generates HTML or Markdown reports showing priority breakdowns, trend lines over time, and actionable recommendations such as "address 10 high-priority items immediately."

## How the Components Interact

The Tech-Debt-Tracker follows a linear pipeline where each component's output becomes the next's input. The workflow proceeds as follows:

1. Run [`debt_scanner.py`](https://github.com/alirezarezvani/claude-skills/blob/main/debt_scanner.py) to generate a JSON inventory of debt items
2. Feed the inventory into [`debt_prioritizer.py`](https://github.com/alirezarezvani/claude-skills/blob/main/debt_prioritizer.py) to produce a prioritized CSV or JSON
3. Process the prioritized data through [`debt_dashboard.py`](https://github.com/alirezarezvani/claude-skills/blob/main/debt_dashboard.py) to create HTML/Markdown reports

This architecture ensures that teams can run the full pipeline or integrate individual components into existing CI/CD workflows.

## Configuration and Extensibility

The Tech-Debt-Tracker offers extensive customization options to adapt to diverse codebases and organizational priorities.

### Customizing Detection Thresholds

Default configuration parameters—including maximum function length, complexity thresholds, and ignore patterns—are defined in `_load_default_config()` within [`debt_scanner.py`](https://github.com/alirezarezvani/claude-skills/blob/main/debt_scanner.py). Teams can override these defaults by providing a custom JSON file via the `--config` flag:

```bash
python3 engineering/tech-debt-tracker/scripts/debt_scanner.py . \
  --config custom_thresholds.json --output scan.json

```

### Adding Language Support

While Python files receive AST-based analysis, other languages use regex patterns within `_scan_generic_file()`. Adding support for new languages requires extending this method with language-specific regex patterns or implementing a new AST analyzer class for languages with available parsing libraries.

### Adjusting Scoring Weights

Organizations can modify `severity_weights` in the scanner configuration or supply custom multipliers to the prioritizer to align scoring with specific risk appetites. This allows teams to weight architectural debt more heavily than documentation debt, for example, by adjusting the respective multipliers in the configuration.

## Practical Implementation Examples

### Running a Complete Analysis Pipeline

Execute the full workflow from command line to generate an executive dashboard:

```bash

# Step 1: Scan the codebase

python3 engineering/tech-debt-tracker/scripts/debt_scanner.py path/to/repo \
  --output scan_report.json --format json

# Step 2: Prioritize findings

python3 engineering/tech-debt-tracker/scripts/debt_prioritizer.py \
  scan_report.json --output prioritized_report.json

# Step 3: Generate dashboard

python3 engineering/tech-debt-tracker/scripts/debt_dashboard.py \
  prioritized_report.json --output debt_dashboard.html

```

### Integrating with GitHub Actions

Automate debt tracking in CI pipelines by adding this workflow step:

```yaml
steps:
  - name: Checkout code
    uses: actions/checkout@v3

  - name: Scan for technical debt
    run: |
      python3 engineering/tech-debt-tracker/scripts/debt_scanner.py . \
        --output debt_scan.json --format json

  - name: Upload scan artifact
    uses: actions/upload-artifact@v3
    with:
      name: debt-scan
      path: debt_scan.json

```

### Programmatic Usage in Python

Embed the scanner directly into Python applications or custom analysis tools:

```python
from engineering.tech_debt_tracker.scripts.debt_scanner import DebtScanner

scanner = DebtScanner()
report = scanner.scan_directory("/my/project")

# `report` is a dict ready for prioritization or custom processing

```

## Summary

- The **Tech-Debt-Tracker** from `alirezarezvani/claude-skills` provides a complete three-stage pipeline for **tracking and prioritizing technical debt** through scanning, economic scoring, and dashboard visualization.
- The **Debt Scanner** ([`debt_scanner.py`](https://github.com/alirezarezvani/claude-skills/blob/main/debt_scanner.py)) uses AST parsing for Python and regex for other languages to generate JSON inventories of debt items.
- The **Debt Prioritizer** ([`debt_prioritizer.py`](https://github.com/alirezarezvani/claude-skills/blob/main/debt_prioritizer.py)) applies interest-rate formulas and WSJF-style scoring to assign `critical`, `high`, `medium`, or `low` priorities based on business impact.
- The **Debt Dashboard** ([`debt_dashboard.py`](https://github.com/alirezarezvani/claude-skills/blob/main/debt_dashboard.py)) aggregates historical data to calculate health scores and generate executive-ready HTML or Markdown reports.
- Teams can customize detection thresholds, add language support, and adjust scoring weights via configuration files and command-line arguments.

## Frequently Asked Questions

### How does the Tech-Debt-Tracker calculate the priority of technical debt items?

The prioritizer calculates an **interest rate** using the formula `Impact × Frequency / Time`, then computes **Cost-of-Delay** as `Interest × Time Until Fix × TeamSizeMultiplier`. These values feed into a WSJF-style scoring algorithm that assigns each item a `priority_score` and categorical label such as `critical`, `high`, `medium`, or `low`.

### Can I use the Tech-Debt-Tracker with programming languages other than Python?

Yes. While the scanner uses AST parsing for Python files, it employs configurable regex patterns via `_scan_generic_file()` for other languages. You can extend support for additional languages by adding new regex patterns or implementing dedicated AST analyzer classes for languages with available parsing libraries.

### How do I integrate the Tech-Debt-Tracker into a CI/CD pipeline?

You can run [`debt_scanner.py`](https://github.com/alirezarezvani/claude-skills/blob/main/debt_scanner.py) as a step in your pipeline to generate JSON reports on every build. For GitHub Actions, checkout your repository, run the scanner with `--output` and `--format json` flags, and upload the resulting JSON as an artifact. This ensures continuous **tracking and prioritizing of technical debt** alongside your regular development workflow.

### Where can I customize the thresholds for detecting technical debt?

Default thresholds—including maximum function length, complexity limits, and ignore patterns—are defined in the `_load_default_config()` function within [`debt_scanner.py`](https://github.com/alirezarezvani/claude-skills/blob/main/debt_scanner.py). Override these by providing a custom JSON configuration file via the `--config` command-line argument when running the scanner.