Tech Debt Tracker

The agent identifies, scores, prioritizes, and tracks technical debt across codebases using AST parsing, cost-of-delay analysis, and trend dashboards.

Workflow

1. Scan codebase -- Run the Debt Scanner against the target repository. It uses AST parsing and pattern matching to detect debt signals across all six categories (code, architecture, test, documentation, dependency, infrastructure).
2. Score each item -- Apply the Severity Scoring Framework. Rate each item on velocity impact, quality impact, productivity impact, and business impact (1-10 each). Estimate effort (XS-XL) and risk level.
3. Calculate interest rate -- For each item, compute

   Interest Rate = Impact Score x Frequency of Encounter

   per sprint. Calculate

   Cost of Delay = Interest Rate x Sprints Until Fix x Team Size Multiplier

   .
4. Prioritize -- Plot items on the Cost-of-Delay vs Effort matrix. Assign priority: Immediate (high cost, low effort), Planned (high cost, high effort), Opportunistic (low cost, low effort), Backlog (low cost, high effort).
5. Allocate sprint capacity -- Apply the Debt-to-Feature Ratio based on current team velocity. Reserve the recommended percentage for debt work.
6. Generate reports -- Produce the Executive Dashboard (health score, trend, top risks, investment recommendation) and the Engineering Dashboard (daily new/resolved, interest rate by component, hotspots).
7. Track trends -- Compare current scan against previous baselines. Alert if debt accumulation rate exceeds paydown rate for two consecutive sprints.

Debt Classification

Severity Scoring Framework

Rate each dimension 1-10:

Effort sizing: XS (1-4 hrs), S (1-2 days), M (3-5 days), L (1-2 weeks), XL (3+ weeks)

Interest Rate and Cost of Delay

Interest Rate = Impact Score x Frequency of Encounter (per sprint)
Cost of Delay = Interest Rate x Sprints Until Fix x Team Size Multiplier

Example:
  Legacy auth module with poor error handling
  Impact: 7  |  Frequency: 15 encounters/sprint  |  Team: 8 devs
  Planned fix: sprint 4 (3 sprints away)

  Interest Rate = 7 x 15 = 105 points/sprint
  Cost of Delay = 105 x 3 x 1.2 = 378 total cost points

Prioritization Matrix

WSJF Alternative

WSJF = (Business Value + Time Criticality + Risk Reduction) / Effort

Each component scored 1-10. Highest WSJF items are prioritized first.

Sprint Allocation (Debt-to-Feature Ratio)

Sprint planning rule: Reserve 20% of sprint capacity for debt. Prioritize items with the highest interest rates. Add "debt tax" to feature estimates when working in high-debt areas.

Debt Item Data Structure

{
  "id": "DEBT-2024-001",
  "title": "Legacy user authentication module",
  "category": "code",
  "subcategory": "error_handling",
  "location": "src/auth/legacy_auth.py:45-120",
  "description": "Authentication error handling uses generic exceptions",
  "impact": { "velocity": 7, "quality": 8, "productivity": 6, "business": 5 },
  "effort": { "size": "M", "risk": "medium", "skill_required": "mid" },
  "interest_rate": 105,
  "cost_of_delay": 378,
  "priority": "high",
  "status": "identified",
  "tags": ["security", "user-experience", "maintainability"]
}

Status lifecycle: Identified > Analyzed > Prioritized > Planned > In Progress > Review > Done | Won't Fix

Refactoring Strategies

Executive Dashboard

TECH DEBT HEALTH
  Overall Score: [0-100]  |  Trend: [improving/declining]
  Cost of Delayed Fixes: [X development days]
  High-Risk Items: [count]

MONTHLY REPORT:
  1. Executive Summary (3 bullet points)
  2. Health Score Trend (6-month view)
  3. Top 3 Risk Items (business impact focus)
  4. Investment Recommendation (resource allocation)
  5. Success Stories (debt resolved last month)

Engineering Dashboard

DAILY:
  New items identified  |  Items resolved  |  Interest rate by component

SPRINT REVIEW:
  Debt points completed vs planned  |  Velocity impact
  Newly discovered debt  |  Team code quality sentiment

Example: Scanning a Python Microservice

# Run debt scanner
python scripts/debt_scanner.py --repo ./payment-service --output debt_inventory.json

# Output summary:
#   Total items found: 47
#   Critical: 3  |  High: 8  |  Medium: 21  |  Low: 15
#
#   Top 3 by cost-of-delay:
#     1. DEBT-001: payment_processor.py - nested exception handling (CoD: 420)
#     2. DEBT-002: db/migrations/ - 12 unapplied migrations (CoD: 315)
#     3. DEBT-003: tests/ - 62% coverage on payment flow (CoD: 280)

# Prioritize items
python scripts/debt_prioritizer.py --inventory debt_inventory.json --sprint-capacity 40

# Generate executive report
python scripts/debt_dashboard.py --inventory debt_inventory.json --baseline previous_scan.json

Quarterly Planning

1. Identify 1-2 major debt themes per quarter
2. Allocate dedicated sprints for large-scale refactoring
3. Plan debt work around major feature releases
4. Track: debt interest rate reduction, velocity improvements, defect rate reduction, code review cycle time

Scripts

Debt Scanner (

debt_scanner.py

)

Scans codebase using AST parsing and pattern matching. Detects all six debt categories. Outputs structured JSON inventory.

Debt Prioritizer (

debt_prioritizer.py

)

Analyses debt inventory using cost-of-delay and WSJF frameworks. Outputs prioritized backlog with sprint allocation recommendations.

Debt Dashboard (

debt_dashboard.py

)

Generates trend reports comparing current scan against baselines. Produces executive and engineering dashboard views.

References

See

REFERENCE.md

Troubleshooting

--config

file_extensions

ignore_patterns

python3.12 scripts/debt_scanner.py

min_duplicate_lines

severity

type

debt_scanner.py

type

severity

debt_items

prioritized_backlog

python -m json.tool <file>

todo_comment

missing_docstring

--sprint-capacity

--sprint-capacity

Success Criteria

• Scan completes in under 60 seconds for repositories up to 100,000 lines of code.
• Every detected debt item includes a unique ID, file path, line number (where applicable), severity, and debt type -- no fields left as null or unknown.
• Health score correlates with manual code review assessments within 15 points on the 0-100 scale when validated against a senior engineer's judgment.
• Prioritized backlog produces a clear top-10 list where the first item has at least 2x the priority score of the tenth item, confirming meaningful differentiation.
• Sprint allocation recommendations fit within the configured capacity (no single sprint exceeds 100% of debt budget) and cover all high-priority items within the first 3 sprints.
• Dashboard trend analysis correctly identifies improving, declining, or stable directions when compared against at least 3 historical snapshots with known trajectories.
• Cost-of-delay calculations produce actionable dollar-equivalent values that engineering managers can use directly in sprint planning and quarterly roadmap discussions.

Scope & Limitations

This skill covers:

• Static detection of code-level, architecture, test, documentation, dependency, and infrastructure debt via AST parsing (Python) and regex pattern matching (all languages).
• Quantitative prioritization of debt items using cost-of-delay, WSJF, and RICE frameworks with configurable team size and sprint capacity.
• Historical trend analysis, health scoring, debt velocity tracking, and executive/engineering dashboard generation from multiple scan snapshots.
• Sprint allocation planning with capacity-aware backlog scheduling and effort estimation by debt type.

This skill does NOT cover:

• Runtime performance profiling or production monitoring -- see

  engineering/performance-profiler

  and

  engineering/observability-designer

  for those concerns.
• Dependency vulnerability scanning (CVE detection) or software composition analysis -- see

  engineering/dependency-auditor

  for security-focused dependency review.
• Automated refactoring or code transformation -- the skill identifies and prioritizes debt but does not modify source code.
• Database schema debt, API contract drift, or infrastructure-as-code drift detection -- see

  engineering/database-schema-designer

  ,

  engineering/api-design-reviewer

  , and

  engineering/migration-architect

  for those domains.

Integration Points

engineering/dependency-auditor

dependency_debt

debt_inventory.json

engineering/performance-profiler

engineering/ci-cd-pipeline-builder

debt_scanner.py

summary.health_score

engineering/pr-review-expert

debt_inventory.json

file_path

engineering/observability-designer

category_distribution

engineering/migration-architect

sprint_allocation

Tool Reference

Debt Scanner (

scripts/debt_scanner.py

)

Purpose: Scans a codebase directory for technical debt signals using AST parsing (Python files) and regex pattern matching (all languages). Detects code smells, large functions, high complexity, duplicate code, TODO comments, and common anti-patterns. Produces a structured JSON inventory and a human-readable text report.

Usage:

python scripts/debt_scanner.py <directory> [options]

Parameters:

directory

--config

max_function_length

max_complexity

ignore_patterns

--output

.json

.txt

--format

both

json

text

both

Example:

python scripts/debt_scanner.py ./src --config custom_thresholds.json --output scan_results --format both

Output Formats:

• JSON: Contains

  scan_metadata

  ,

  summary

  (files scanned, lines scanned, health score, debt density, priority/type breakdowns),

  debt_items

  (array of debt objects with id, type, description, file_path, severity, metadata, priority_score, priority),

  file_statistics

  , and

  recommendations

  .
• Text: Human-readable report with header, summary statistics, priority breakdown, top 10 debt items, and numbered recommendations.

Debt Prioritizer (

scripts/debt_prioritizer.py

)

Purpose: Takes a debt inventory (from the scanner or a manual JSON file) and enriches each item with effort estimates, business impact scores, interest rate calculations, and cost-of-delay values. Produces a prioritized backlog with sprint allocation recommendations using one of three frameworks: cost-of-delay, WSJF, or RICE.

Usage:

python scripts/debt_prioritizer.py <inventory_file> [options]

Parameters:

inventory_file

--output

.json

.txt

--format

both

json

text

both

--framework

cost_of_delay

cost_of_delay

wsjf

rice

--team-size

5

--sprint-capacity

80

Example:

python scripts/debt_prioritizer.py scan_results.json --framework wsjf --team-size 8 --sprint-capacity 120 --output prioritized --format json

Output Formats:

• JSON: Contains

  metadata

  (analysis date, framework, team size, sprint capacity),

  prioritized_backlog

  (enriched items sorted by priority score, each with

  effort_estimate

  ,

  business_impact

  ,

  interest_rate

  ,

  cost_of_delay

  ,

  category

  ,

  impact_tags

  ),

  sprint_allocation

  (total debt hours, capacity per sprint, sprint plan with item assignments),

  insights

  (category distribution, effort breakdown, quick wins count, cost totals),

  charts_data

  (scatter, pie, timeline, interest trend arrays), and

  recommendations

  .
• Text: Executive summary with total effort and cost-of-delay, sprint allocation plan (first 3 sprints with top items), top 10 priority items with scores and tags, and numbered recommendations.

Debt Dashboard (

scripts/debt_dashboard.py

)

Purpose: Takes one or more historical debt inventory files (from the scanner or prioritizer) and generates trend analysis, debt velocity tracking (accruing vs. paying down), health score timelines, forecasts, and an executive summary. Supports loading files individually or from a directory.

Usage:

python scripts/debt_dashboard.py [files...] [options]

Parameters:

files

--input-dir

*.json

files

--output

.json

.txt

--format

both

json

text

both

--period

monthly

weekly

monthly

quarterly

--team-size

5

Example:

python scripts/debt_dashboard.py --input-dir ./debt_scans/ --period quarterly --team-size 10 --output dashboard --format both

Output Formats:

• JSON: Contains

  metadata

  (generated date, period, snapshot count, date range, team size),

  executive_summary

  (overall status, health score, status message, key insights, total debt items, effort hours, high priority count, velocity impact percent),

  current_health

  (overall score, debt density, velocity impact, quality score, maintainability score, technical risk score),

  trend_analysis

  (per-metric trend direction, change rate, correlation strength, forecast, confidence interval),

  debt_velocity

  (per-period new/resolved items, net change, velocity ratio, effort hours added/resolved),

  forecasts

  (3-month and 6-month projections for health, debt count, risk),

  recommendations

  (prioritized strategic actions with category, impact, effort),

  visualizations

  (health timeline, debt accumulation, category distribution, velocity chart, effort trend arrays), and

  detailed_metrics

  .
• Text: Executive summary with status and key metrics, current health metrics, trend analysis with directional indicators, and top 5 strategic recommendations with priority, impact, and effort ratings.