6.9 KiB
6.9 KiB
description, allowed-tools
| description | allowed-tools |
|---|---|
| tech-debt | 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
# 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)
-
Ask: "Generate stories for critical debt? (YES/NO)"
-
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
-
Ask: "Save report to docs/08-project/? (YES/NO)"
-
If YES:
- Save to docs/08-project/tech-debt-.md
- Update docs/08-project/README.md with link
-
Suggest adding to roadmap:
- Reserve 10-20% of each sprint for debt reduction
- Add debt review to retrospectives
INTEGRATION
Story Template for Debt
---
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):
- 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