Scenario 12: Technical Debt

Tech lead identifying, quantifying, and planning repayment of technical debt using CPG-powered analysis.

Table of Contents

Quick Start

# Select Tech Debt Scenario
/select 12

How It Works

Intent Classification

When you ask a tech debt question, the IntentDetector classifies it into one of four types using keyword matching (supports both English and Russian queries):

Intent Keywords (EN) Keywords (RU) Routed To
debt_metrics debt score, calculate debt, debt summary показатель долга, рассчитать долг DebtScanHandler
quick_wins quick wins, easy fixes, low-hanging быстрые победы, лёгкие исправления QuickWinsHandler
prioritization prioritize, rank debt, impact vs effort приоритизация, ранжирование долга Full pipeline
repayment_plan repayment plan, sprint plan, pay off debt план погашения, спринт-план Full pipeline

Two-Phase Architecture

The tech debt scenario uses a two-phase processing pipeline:

User Query
    |
    v
[Phase 1] Handler-based (template responses, no LLM)
    |-- IntentDetector        → classify query intent
    |-- DebtScanHandler       → structured debt metrics report
    |-- QuickWinsHandler      → structured quick wins report
    |
    v (if handler cannot answer)
[Phase 2] Full LLM pipeline
    |-- DebtCalculator.detect_all_debt()
    |-- PrioritizationEngine.prioritize_debt()
    |-- RepaymentPlanner.create_plan()
    |-- LLM generates natural language response

Phase 1 (handler-based) provides instant structured answers for debt_metrics and quick_wins intents — no LLM call needed. Phase 2 (LLM fallback) handles prioritization and repayment_plan intents requiring synthesis across all three agents.

Three Agents

The scenario is powered by three specialized agents in src/tech_debt/debt_agents.py:

Agent Purpose Key Methods
DebtCalculator Detect debt items using 6 patterns, calculate metrics detect_all_debt(), calculate_metrics()
PrioritizationEngine Rank debt by ROI, identify quick wins and strategic items prioritize_debt(), get_quick_wins(), get_strategic_items()
RepaymentPlanner Generate sprint-based repayment plans create_plan(velocity, max_sprints)

Debt Detection

6 Debt Patterns

The DebtCalculator identifies technical debt through 6 specialized patterns, each with SQL queries, thresholds, and weights:

Pattern Category Description
TODO_COMMENTS maintenance TODO/FIXME/HACK/XXX comments in code
DEPRECATED_API maintenance Usage of deprecated APIs and functions
CODE_DUPLICATION code_quality Duplicate code blocks detected via AST
LONG_METHODS complexity Functions exceeding 50 lines
COMPLEX_METHODS complexity Functions with cyclomatic complexity > 10
DEAD_CODE unused_code Unreferenced functions and variables

Each pattern runs a CPG query against the DuckDB database and produces DebtItem instances with severity, effort estimate, and fix suggestions.

4 Debt Categories

Debt items are classified into four categories:

Category Patterns Focus
code_quality CODE_DUPLICATION Maintainability and readability
maintenance TODO_COMMENTS, DEPRECATED_API Pending work and obsolete patterns
complexity LONG_METHODS, COMPLEX_METHODS Structural complexity
unused_code DEAD_CODE Dead weight in the codebase

DebtItem Data Model

Each detected debt item is represented as a DebtItem with 12 fields:

Field Type Description
name str Function or symbol name
file_path str Source file path
line_number int Line number in source
pattern_type str Which pattern detected it
severity str critical / high / medium / low
effort_hours float Estimated hours to fix
description str Human-readable description
category str Debt category
confidence float Detection confidence (0.0–1.0)
impact_score float Impact on codebase (0.0–10.0)
fix_suggestion str Recommended fix
metadata dict Additional pattern-specific data

Debt Scan Examples

> Calculate technical debt score

╭─────────────── Tech Debt Summary ───────────────────────────╮
│                                                              │
│  Overall Technical Debt Score: 34/100 (Moderate)             │
│                                                              │
│  Category Breakdown:                                         │
│                                                              │
│  Complexity:     42%  ████████░░  (LONG_METHODS, COMPLEX)   │
│    - 23 functions over complexity threshold                  │
│    - 5 functions over 300 lines                              │
│                                                              │
│  Maintenance:    28%  █████░░░░░  (TODO, DEPRECATED_API)    │
│    - 156 TODO/FIXME/HACK comments                           │
│    - 12 deprecated API usages                                │
│                                                              │
│  Code Quality:   18%  ████░░░░░░  (CODE_DUPLICATION)        │
│    - 15 clone clusters, ~450 duplicated lines                │
│                                                              │
│  Unused Code:    12%  ██░░░░░░░░  (DEAD_CODE)               │
│    - 34 unreferenced functions                               │
│                                                              │
╰──────────────────────────────────────────────────────────────╯

Debt Metrics

DebtMetrics Fields

The DebtCalculator.calculate_metrics() computes quantitative metrics from all detected DebtItem instances:

Field Type Description
total_items int Total number of debt items detected
total_effort_hours float Total estimated hours to fix all debt
debt_ratio float Technical debt as ratio of total codebase effort
by_severity dict Breakdown: critical / high / medium / low
by_category dict Breakdown by 4 categories
by_pattern dict Breakdown by 6 patterns
average_confidence float Mean confidence across all items
estimated_cost float Dollar estimate based on effort × hourly rate

Metrics Example

> Show debt metrics

  Total items:        234
  Total effort:       180 hours
  Debt ratio:         0.12 (12% of codebase effort)
  Estimated cost:     $18,000

  By severity:
    critical:  12   high:  45   medium:  98   low:  79

  By category:
    complexity:    89   maintenance:  67
    code_quality:  44   unused_code:  34

Prioritization

ROI Scoring

The PrioritizationEngine.prioritize_debt() ranks every DebtItem by return on investment:

ROI score = impact_score / effort_hours

Higher ROI means bigger impact for less effort — these items should be fixed first.

Each PrioritizedDebt result contains:

Field Type Description
item DebtItem Original debt item
priority_score float Composite priority (0.0–10.0)
roi_score float Impact / effort ratio
quick_win bool True if qualifies as quick win
strategic bool True if qualifies as strategic
dependencies int Number of dependent items
rationale str Why this priority was assigned

Quick Wins

The PrioritizationEngine.get_quick_wins() identifies items that are fast to fix and have reliable detection:

Quick win criteria:
  effort_hours ≤ 2  AND  confidence ≥ 0.7

Quick wins are ideal for sprint fillers or onboarding tasks — high confidence means low risk of false positives.

Strategic Items

The PrioritizationEngine.get_strategic_items() identifies items with outsized architectural impact:

Strategic item criteria:
  impact_score ≥ 8  OR  dependencies ≥ 3

Strategic items require dedicated sprint capacity but yield significant long-term improvements.

Prioritization Example

> Prioritize debt items

  Prioritized Debt (by ROI):
    1. [QUICK WIN] Remove dead function old_format_help()
       ROI: 9.2  Effort: 0.5h  Impact: 4.6  Confidence: 0.95

    2. [QUICK WIN] Delete TODO block in pg_type.c:234
       ROI: 7.0  Effort: 1.0h  Impact: 7.0  Confidence: 0.85

    3. [STRATEGIC] Split exec_simple_query() — complexity 47
       ROI: 3.1  Effort: 8.0h  Impact: 24.5  Dependencies: 5

    4. [STRATEGIC] Deduplicate scan init routines — 3 files
       ROI: 2.8  Effort: 6.0h  Impact: 16.8  Dependencies: 3

  Quick wins: 45 items (total ~30h)
  Strategic items: 12 items (total ~96h)

Repayment Planning

Sprint-Based Planning

The RepaymentPlanner.create_plan() distributes prioritized debt items across sprints:

  • team_velocity = 40 hours/sprint (configurable)
  • max_sprints = 6 (configurable)
  • Items are assigned to sprints in priority order until velocity is exhausted
  • Each sprint includes risk assessment and recommendations

RepaymentPlan Data Model

Field Type Description
sprints list Per-sprint item assignments with effort totals
total_sprints int Number of sprints in the plan
total_effort float Total hours across all sprints
items_addressed int Items that fit within max_sprints
items_remaining int Items that don’t fit
velocity float Hours per sprint
completion_percentage float % of total debt addressed
risk_assessment str Overall risk evaluation
recommendations list Actionable recommendations
metadata dict Additional planning data

Repayment Example

> Create repayment plan for tech debt

╭─────────────── Repayment Plan ────────────────────────────╮
│                                                            │
│  Velocity: 40 hours/sprint                                 │
│  Sprints: 4 of 6 max                                      │
│  Completion: 78% of total debt addressed                   │
│                                                            │
│  Sprint 1 (38h):                                           │
│    - 12 quick wins (TODO cleanup, dead code removal)       │
│    - Risk: LOW                                             │
│                                                            │
│  Sprint 2 (40h):                                           │
│    - Split exec_simple_query() (8h)                        │
│    - Remove deprecated API calls (6h)                      │
│    - 8 quick wins (26h)                                    │
│    - Risk: MEDIUM                                          │
│                                                            │
│  Sprint 3 (36h):                                           │
│    - Deduplicate scan routines (6h)                        │
│    - Reduce coupling in executor (12h)                     │
│    - 6 quick wins (18h)                                    │
│    - Risk: MEDIUM                                          │
│                                                            │
│  Sprint 4 (32h):                                           │
│    - Remaining complexity items                            │
│    - Risk: LOW                                             │
│                                                            │
│  Items remaining: 52 (22% — schedule in future sprints)    │
│                                                            │
╰────────────────────────────────────────────────────────────╯

Config Hygiene

The tech debt scenario includes config orphan detection — a static analysis tool that cross-references config.yaml, unified_config.py dataclasses, and code usage to find dead or missing configuration parameters.

6 Orphan Types

Type Code Description
yaml_unused R1 YAML section has no @property and no code references
code_orphan R3 Code references cfg.X but no @property X exists in schema
orphaned_dataclass R5 Dataclass has no matching @property
unused_default R6 Dataclass field not in YAML and not referenced in code

CLI Usage

# Full scan (all severity levels)
python -m src.cli dogfood config-check

# Errors only (used in CI)
python -m src.cli dogfood config-check --level error --format text

# JSON output with fix suggestions
python -m src.cli dogfood config-check --format json --fix-suggestions

# Custom paths (for other projects)
python -m src.cli dogfood config-check --config my_config.yaml --schema my_schema.py --source src/ lib/

Audit Integration

Config orphan findings feed into the audit composite (Q3 redundant code and Q9 maintainability dimensions). The OrphanConfigHandler in S12 handles config_hygiene and orphan_config query intents.

CLI & MCP Usage

# Query-based debt analysis
python -m src.cli query "Calculate technical debt score"

# Deep analysis with LLM
python -m src.cli exec --prompt "Create a repayment plan for tech debt"

# Quick wins detection
python -m src.cli query "Find quick wins in tech debt"

# Prioritization
python -m src.cli query "Prioritize debt items by ROI"

MCP tool: codegraph_tech_debt — available in IDE integrations for interactive debt analysis.

Example Questions

Debt Metrics: - “Calculate technical debt score” - “Show debt metrics summary” - “What is the debt ratio?”

Quick Wins: - “Find quick wins in tech debt” - “Show easy fixes with high confidence” - “What can I fix in under 2 hours?”

Prioritization: - “Prioritize debt by impact and effort” - “Rank debt items by ROI” - “Show strategic debt items”

Repayment Planning: - “Create a sprint plan for debt repayment” - “How many sprints to address critical debt?” - “Generate repayment plan with 30h velocity”

Config Hygiene: - “Check config for unused parameters” - “Find orphan config keys” - “Run config hygiene scan”

Pattern-Specific: - “Find TODO/FIXME comments” - “Find deprecated API usage” - “Find long methods over 50 lines” - “Find dead code”

  • Refactoring (S05) — S05 focuses on refactoring suggestions using TechnicalDebtDetector, ImpactAnalyzer, and RefactoringPlanner from src/refactoring/. S12 focuses on debt quantification and repayment planning using DebtCalculator, PrioritizationEngine, and RepaymentPlanner from src/tech_debt/. S05 answers “what to refactor”; S12 answers “how much debt and when to pay it off”
  • Performance (S06) — Performance-related debt
  • Compliance (S08) — Standards compliance debt
  • Mass Refactoring (S13) — Large-scale debt reduction through automated symbol migrations