AgileFlow

/debt

PreviousNext

Track and prioritize technical debt items

/debt

Track and visualize technical debt across the codebase. Identify, categorize, and prioritize refactoring work with data-driven scoring.

Quick Start

/agileflow:debt

Runs a quick scan and generates a debt report with default settings.

Or with custom options:

/agileflow:debt SCAN=full OUTPUT=report THRESHOLD=medium

Parameters

ParameterRequiredDefaultDescription
SCANNoquickScan depth: quick (flagged areas only) or full (entire codebase)
OUTPUTNoreportOutput type: report, stories, or both
THRESHOLDNomediumMinimum severity: high, medium, or low

What It Detects

The debt scanner identifies multiple types of technical debt:

Code Quality Signals

  • TODO/FIXME/HACK comments
  • Long functions (>50 lines)
  • High cyclomatic complexity (>10)
  • Duplicated code blocks
  • Large files (>500 lines)
  • Deep nesting (>4 levels)
  • God objects (>10 methods)
  • Low test coverage (under 70%)

Story-Based Debt

Searches stories tagged with tech-debt: true or with "refactor" or "cleanup" in the title.

Architecture Debt

Checks ADRs for deprecated decisions or documented negative consequences.

Git History Analysis

  • Files with high churn (frequently modified)
  • Files with many authors (unclear ownership)
  • Old branches not yet merged

Linter Output

Parses output from ESLint, TypeScript, Pylint, SonarQube, and coverage reports.

Debt Categories

Technical debt is organized into seven categories:

CategoryDescriptionExamples
ArchitectureWrong abstractions, tight coupling, missing patternsService coupling, circular dependencies
Code QualityDuplication, complexity, inconsistent styleCopy-paste code, high complexity
DocumentationMissing, outdated, or incomplete docsUndocumented APIs, stale guides
TestingLow coverage, flaky tests, missing E2ENo unit tests, missing integration tests
SecurityOutdated deps, exposed secrets, weak authCVE-vulnerable packages, hardcoded tokens
PerformanceN+1 queries, memory leaks, slow opsInefficient algorithms, memory bloat
DependenciesOutdated packages, unmaintained librariesYears-old libraries, abandoned projects

Scoring Formula

Each debt item receives a score from 0-100:

Score = (Severity × Scope × Pain) / 10
 
Severity: 1-10 (impact level)
Scope:    1-10 (files affected)
Pain:     1-10 (developer frustration)

Severity Levels

  • Low (1-3): Minor issue, doesn't block anything
  • Medium (4-6): Moderate issue, slows down development
  • High (7-9): Significant issue, blocks features or causes bugs
  • Critical (10): Urgent, causes production issues or blocks work

Examples

Quick Scan (Default)

/agileflow:debt

Scans areas marked with TODO/FIXME and tagged stories. Generates report.

Full Codebase Scan

/agileflow:debt SCAN=full

Deep scan of entire codebase including complexity analysis, duplication detection, and coverage analysis.

Generate Stories for Critical Debt

/agileflow:debt SCAN=quick OUTPUT=stories THRESHOLD=high

Finds critical debt items and optionally creates stories for them.

Generate Both Report and Stories

/agileflow:debt SCAN=full OUTPUT=both THRESHOLD=medium

Creates debt report and generates stories for debt items above medium severity.

Output Example

# Technical Debt Report
 
**Generated**: 2025-12-24T10:30:00Z
**Total Debt Items**: 42
**Critical**: 3 | **High**: 12 | **Medium**: 18 | **Low**: 9
**Total Estimated Effort**: 48 days
 
---
 
## Critical Debt (Score >80)
 
### 1. Auth service tightly coupled to database
**Type**: Architecture | **Score**: 87
**Impact**: Blocks US-0055 (Add OAuth), US-0061 (Add 2FA)
**Files**: src/services/auth.ts (287 lines, complexity 18)
**Estimate**: 3-5 days
**ADR**: ADR-0003 recommends service layer separation (not implemented)
 
### 2. Missing integration tests for payment flow
**Type**: Testing | **Score**: 85
**Impact**: High risk for regressions, blocking production
**Files**: src/api/payments/*.ts (12 files, 0% coverage)
**Last Incident**: 2025-09-15 (payment processing bug)
**Estimate**: 2-3 days
 
---
 
## High Debt (Score 60-80)
[12 items...]
 
---
 
## Summary by Category
 
| Category | Count | Avg Score | Estimated Effort |
|----------|-------|-----------|------------------|
| Architecture | 8 | 72 | 15 days |
| Code Quality | 15 | 58 | 8 days |
| Testing | 10 | 65 | 12 days |
| Security | 3 | 78 | 5 days |
| Performance | 4 | 61 | 6 days |
 
---
 
## Debt Heatmap (Most Problematic Files)
 
- src/services/auth.ts: 3 items (architecture, complexity, coupling)
- src/api/payments/process.ts: 2 items (no tests, deprecated API)
- src/utils/legacy.ts: 2 items (duplication, no docs)
 
---
 
## Recommendations
 
1. **Immediate** (Critical): Address auth refactor and payment tests
2. **This Sprint**: Tackle 3 high-severity items (by ROI)
3. **Next Sprint**: Reserve 20% capacity for debt reduction
4. **Ongoing**: Require tests for all new code (enforce in CI)

Workflow

After generating a debt report, you can:

1. Review the Report

Understand what debt exists and where it is.

2. Generate Stories (Optional)

/agileflow:debt OUTPUT=stories

Creates stories for critical debt items with:

  • Acceptance criteria focused on "before/after" state
  • Impact analysis
  • Estimated effort
  • References to affected features

3. Save to Documentation

/agileflow:debt OUTPUT=report

Saves report to docs/08-project/tech-debt-YYYYMMDD.md and updates the README with a link.

4. Create Debt Epic

If many critical items exist, creates an epic:

  • EP-XXXX: Technical Debt Reduction
  • Stories for top 5 critical items
  • Tracks debt reduction progress

Using Debt Information

Plan Sprints

Reserve 10-20% of each sprint for debt reduction:

/agileflow:sprint --include-debt --debt-threshold=high

Retrospectives

Track debt reduction in retrospectives:

/agileflow:retro --analyze-debt

Dashboard

Create a debt dashboard that updates weekly:

docs/08-project/debt-dashboard.md
 
# Debt Dashboard (Weekly)
 
Week 52: 42 items (↑ from 39)
Week 51: 39 items (↓ from 43)
 
Critical: 3 items (target: reduce to 1 this sprint)

Best Practices

  1. Be Honest About Estimates: Err on the high side
  2. Link to Features: Prioritize debt blocking new work
  3. Celebrate Reductions: Recognize debt paydown in retros
  4. Prevent Accumulation: Enforce testing in CI for new code
  5. Review Regularly: Run debt scan monthly or quarterly

Debt Prevention

Add debt review to your CI/CD:

# Run weekly technical debt scan
- cron: '0 0 * * 1'  # Every Monday
  name: Technical debt scan
  run: /agileflow:debt SCAN=full OUTPUT=report

Integration with Development

When implementing features, check if they create debt:

# Before completing story
/agileflow:debt SCAN=quick THRESHOLD=high
 
# If debt created, track in story
/agileflow:status STORY=US-0042 TECH_DEBT=true DEBT_SCORE=42

Story Template for Debt

When creating stories for debt items:

---
story_id: US-XXXX
title: Refactor auth service to separate concerns
type: tech-debt
debt_score: 87
estimate: 3d
---
 
## Current State (Before)
- auth.ts contains DB queries, business logic, and HTTP handling
- 287 lines, complexity 18
- Hard to test, hard to extend
 
## Desired State (After)
- Clear separation: AuthService, AuthRepository, AuthController
- Each \<100 lines, complexity \<8
- 80%+ test coverage
- Enables US-0055 (OAuth)
 
## Acceptance Criteria
- [ ] AuthRepository handles all DB operations
- [ ] AuthService contains only business logic
- [ ] AuthController handles only HTTP/routing
- [ ] Tests cover each layer independently
- [ ] All existing auth tests still pass

Related Commands

  • /diagnose - System health diagnostics
  • /metrics - Analytics and metrics dashboard
  • /story - Create stories for debt items
  • /epic - Create debt reduction epic
  • /retro - Include debt analysis in retrospectives
  • /board - View debt-related stories on board