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

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) 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) 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) 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 to generate a JSON inventory of debt items
2. Feed the inventory into debt_prioritizer.py to produce a prioritized CSV or JSON
3. Process the prioritized data through 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. Teams can override these defaults by providing a custom JSON file via the --config flag:

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:

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

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:

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) uses AST parsing for Python and regex for other languages to generate JSON inventories of debt items.
• The Debt Prioritizer (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) 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 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. Override these by providing a custom JSON configuration file via the --config command-line argument when running the scanner.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}