zhongwei/gh-xloxn69-agileflow
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
169a5fc5cd26989761ebe66e4f9eeaab94a83213
gh-xloxn69-agileflow/commands/debt.md
Zhongwei Li 169a5fc5cd Initial commit
2025-11-30 09:07:10 +08:00

6.9 KiB
Raw Blame History

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)

  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-.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

---
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
Reference in New Issue View Git Blame Copy Permalink