---
description: tech-debt
allowed-tools: Bash, Read, Edit, Write, Glob, Grep
---

# tech-debt

Track and visualize technical debt across the codebase.

## Prompt

ROLE: Technical Debt Tracker

OBJECTIVE
Identify, categorize, and prioritize technical debt to guide refactoring efforts.

INPUTS (optional)
- SCAN=full|quick (default: quick - only flagged areas)
- OUTPUT=report|stories|both (default: report)
- THRESHOLD=high|medium|low (default: medium - minimum severity to report)

DEBT DETECTION

### 1. Code Quality Signals
Scan for common debt indicators:
- TODO/FIXME/HACK comments
- Long functions (>50 lines)
- High cyclomatic complexity (>10)
- Duplicated code blocks (copy-paste)
- Large files (>500 lines)
- Deep nesting (>4 levels)
- God objects (classes with >10 methods)
- Low test coverage (<70%)

### 2. Story Tags
Search docs/06-stories/ for:
- Stories tagged `tech-debt: true`
- Stories with status=blocked by debt
- Stories with "refactor" or "cleanup" in title

### 3. ADR Analysis
Check docs/03-decisions/ for:
- ADRs with status=Deprecated (implementations may still exist)
- ADRs with documented "negative consequences"
- ADRs noting "temporary solution"

### 4. Git History
Analyze:
- Files with high churn (frequently modified)
- Files with many authors (ownership unclear)
- Old branches not merged (potential context loss)

### 5. Linter/Analyzer Output
Parse output from:
- ESLint, TSLint, Pylint
- SonarQube, CodeClimate
- Code coverage reports

CATEGORIZATION

Group debt by type:
- **Architecture**: Wrong abstractions, tight coupling, missing patterns
- **Code Quality**: Duplication, complexity, inconsistent style
- **Documentation**: Missing, outdated, or incomplete docs
- **Testing**: Low coverage, flaky tests, missing E2E
- **Security**: Outdated dependencies, exposed secrets, weak auth
- **Performance**: N+1 queries, memory leaks, slow operations
- **Dependencies**: Outdated packages, unmaintained libraries

SCORING

Each debt item gets a score (0-100):
- **Severity**: Low (1-3), Medium (4-6), High (7-9), Critical (10)
- **Scope**: How many files affected (1-10 scale)
- **Pain**: Developer frustration (1-10 scale)

Score = Severity × Scope × Pain / 10

DEBT REPORT
```markdown
# Technical Debt Report

**Generated**: <ISO timestamp>
**Total Debt Items**: 42
**Critical**: 3 | **High**: 12 | **Medium**: 18 | **Low**: 9

---

## Critical Debt (Score >80)

### 1. Auth service tightly coupled to database layer
**Type**: Architecture
**Score**: 87
**Impact**: Blocks US-0055 (Add OAuth), US-0061 (Add 2FA)
**Files**: src/services/auth.ts (287 lines, complexity 18)
**ADR**: ADR-0003 recommends service layer separation (not implemented)
**Estimate**: 3-5 days to refactor
**Stories**:
- Create epic: EP-0010 "Refactor auth architecture"
- Stories: Separate concerns, add interface, migrate callers

---

### 2. Missing integration tests for payment flow
**Type**: Testing
**Score**: 85
**Impact**: High risk for regressions, blocking production deploy
**Files**: src/api/payments/*.ts (12 files, 0% integration coverage)
**Last incident**: 2025-09-15 (payment bug in production)
**Estimate**: 2-3 days
**Stories**:
- US-XXXX: Write integration tests for payment flow

---

### 3. Unmaintained dependency: old-oauth-lib (3 years outdated)
**Type**: Security
**Score**: 82
**Impact**: 2 known CVEs, blocks security audit
**Files**: 8 files import this library
**ADR**: ADR-0012 marked this for replacement (6 months ago)
**Estimate**: 1-2 days to migrate to modern-oauth-lib
**Stories**:
- US-XXXX: Migrate from old-oauth-lib to modern-oauth-lib

---

## 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 |
| Documentation | 2 | 45 | 2 days |

**Total Estimated Effort**: 48 days

---

## Trend Analysis

Debt added this sprint: +5 items
Debt resolved this sprint: -2 items
Net change: +3 items ⚠️

---

## Recommendations

1. **Immediate** (Critical): Address auth refactor and payment tests
2. **This Sprint**: Tackle 3 high-severity items (choose by ROI)
3. **Next Sprint**: Reserve 20% capacity for debt reduction
4. **Ongoing**: Require tests for all new code (enforce in CI)

---

## Debt Heatmap

Most problematic files:
- src/services/auth.ts: 3 debt items (arch, complexity, coupling)
- src/api/payments/process.ts: 2 debt items (no tests, deprecated API)
- src/utils/legacy.ts: 2 debt items (duplication, no docs)
```

ACTIONS (after user review)

1. Ask: "Generate stories for critical debt? (YES/NO)"
2. If YES:
   - Create epic: "EP-XXXX: Technical Debt Reduction"
   - Create stories for top 5 critical items
   - Use templates with AC focused on "before/after" state

3. Ask: "Save report to docs/08-project/? (YES/NO)"
4. If YES:
   - Save to docs/08-project/tech-debt-<YYYYMMDD>.md
   - Update docs/08-project/README.md with link

5. Suggest adding to roadmap:
   - Reserve 10-20% of each sprint for debt reduction
   - Add debt review to retrospectives

INTEGRATION

### Story Template for Debt
```markdown
---
story_id: US-XXXX
title: Refactor auth service to separate concerns
type: tech-debt
debt_score: 87
estimate: 3d
---

## Context
Auth service is tightly coupled to database layer, blocking OAuth integration.

## 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
- [ ] No breaking changes to API

## References
- ADR-0003: Service layer separation
- Blocked stories: US-0055, US-0061
```

### Dashboard Integration
Suggest creating a simple dashboard:
```
docs/08-project/debt-dashboard.md

# Debt Dashboard (Updated Weekly)

## Trend
Week 42: 42 items (↑ from 39)
Week 41: 39 items (↓ from 43)

## Critical Items: 3
[List with links to stories]

## This Sprint Goal
Reduce critical debt from 3 → 1
```

AUTOMATION

Suggest adding to CI (weekly):
```yaml
- cron: '0 0 * * 1'  # Monday
- name: Technical debt scan
  run: npx claude-code /AgileFlow:tech-debt SCAN=full OUTPUT=report
```

RULES
- Never auto-create stories without approval
- Be honest about estimates (err on high side)
- Link debt items to blocked stories when possible
- Prioritize debt that blocks future work
- Celebrate debt reduction in retrospectives

OUTPUT
- Technical debt report (markdown)
- Optional: Stories for top debt items
- Optional: Trend analysis
- Recommendations for debt reduction