debt-audit

Purpose: Comprehensive technical debt inventory with ROI-based prioritization

Pattern: Parallel domain audits → unified backlog with aging analysis

---

Orchestration

You are the tech-lead coordinating a technical debt audit. Your mission:

1. Spawn parallel auditors (5 agents):

   • refactoring-strategist: Code quality debt (duplication, complexity, smells)
   • performance-analyst: Performance debt (bottlenecks, inefficiencies)
   • security-auditor: Security debt (vulnerabilities, outdated deps)
   • test-strategist: Test debt (coverage gaps, flaky tests)
   • doc-strategist: Documentation debt (missing/outdated docs)

2. Each auditor produces:

   ## [Domain] Debt Items
   
   ### [Item Title]
   - **Impact**: High/Medium/Low (business/user/dev impact)
   - **Effort**: S/M/L/XL (small/medium/large/extra-large)
   - **Age**: X months (git log analysis)
   - **Location**: file:line references
   - **Description**: What's wrong and why it matters
   - **Remediation**: Concrete fix steps

3. Calculate ROI score for each item:

   ROI = (Impact Score) / (Effort Score)
   
   Impact: High=3, Medium=2, Low=1
   Effort: S=1, M=2, L=3, XL=4
   
   Priority tiers:
   - Critical: ROI ≥ 2.0 (high impact, low effort)
   - High:     ROI 1.0-2.0
   - Medium:   ROI 0.5-1.0
   - Low:      ROI < 0.5

4. Age multiplier (older debt gets priority boost):

   Age < 3mo:   1.0x
   Age 3-6mo:   1.1x
   Age 6-12mo:  1.25x
   Age > 12mo:  1.5x

5. Synthesize final roadmap:

   • Group by priority tier
   • Within tier, sort by adjusted ROI (base ROI × age multiplier)
   • Include quick wins section (High impact, S effort)
   • Flag critical blockers (security/performance issues blocking features)

---

Workflow

# 1. Spawn team
spawnTeam("debt-audit", "tech-lead")

# 2. Create audit tasks (parallel)
for domain in [code, perf, security, test, docs]
    createTask(
        domain + "-audit",
        "Inventory all " + domain + " debt with impact/effort/age",
        agent=domain + "-specialist"
    )

# 3. Wait for all audits → aggregate results

# 4. Calculate ROI scores → prioritize

# 5. Produce final backlog report

---

Output Format

# Technical Debt Backlog

**Generated**: YYYY-MM-DD
**Total Items**: N
**Critical Items**: X (ROI ≥ 2.0)

---

## Executive Summary

- **Quick Wins**: X items (high impact, small effort) - recommend tackling first
- **Critical Blockers**: Y items blocking features/security
- **Oldest Debt**: Item Z (NN months old)

---

## Priority: CRITICAL (ROI ≥ 2.0)

### [Item Title] (ROI: 3.0, Age: 8mo)
- **Domain**: Code Quality
- **Impact**: High - causes 40% of customer bugs
- **Effort**: S (2 days)
- **Location**: `src/core/parser.ts:145-200`
- **Fix**: Refactor nested conditionals into strategy pattern
- **Dependencies**: None

[... more critical items ...]

---

## Priority: HIGH (ROI 1.0-2.0)

[... high priority items ...]

---

## Priority: MEDIUM (ROI 0.5-1.0)

[... medium priority items ...]

---

## Priority: LOW (ROI < 0.5)

[... low priority items, consider deferring ...]

---

## Debt Distribution

- **Code Quality**: X items (Y% of total)
- **Performance**: X items
- **Security**: X items
- **Test Coverage**: X items
- **Documentation**: X items

---

## Recommended Action Plan

1. **Sprint 1**: All Critical items (Est: N days)
2. **Sprint 2**: High-priority quick wins
3. **Ongoing**: Allocate 20% capacity to Medium tier
4. **Re-audit**: Schedule next audit in 3 months

---

Agent Instructions

For Domain Auditors

When assigned an audit task:

1. Scan codebase for your domain:

   • Use rg, fd, static analysis tools
   • Check for patterns/anti-patterns
   • Review recent bug reports related to your domain

2. Assess age for each item:

   # Find when problematic code was introduced
   git log -p --all -S "pattern" -- path/to/file
   # or blame for specific lines
   git blame -L start,end path/to/file

3. Score honestly:

   • Impact: Would fixing this improve user/dev experience significantly?
   • Effort: Realistic estimate (S=1-2d, M=3-5d, L=1-2w, XL=>2w)

4. Provide context:

   • Why is this debt? (rushed deadline, evolving requirements, lack of knowledge)
   • What's the risk of NOT fixing? (accumulates interest, blocks features)

5. Report findings to tech-lead via message

For Tech-Lead

1. Coordinate audits: Spawn agents, assign tasks, monitor progress
2. Aggregate results: Collect all domain reports
3. Calculate scores: Apply ROI formula + age multiplier
4. Resolve conflicts: If items overlap domains, merge/deduplicate
5. Produce report: Final backlog with actionable recommendations
6. Present to user: Clear executive summary + detailed breakdown

---

Success Criteria

• All 5 domains audited thoroughly
• Every debt item has impact/effort/age/location
• ROI scores calculated consistently
• Backlog sorted by adjusted priority
• Quick wins identified (≥3 items recommended for immediate action)
• Report is actionable (clear next steps)

---

Notes

• Debt is not failure - it's a tradeoff. The goal is visibility and prioritization.
• Age matters - old debt has more context loss, harder to fix later
• ROI is a guide - use judgment for strategic items (e.g., security always critical)
• Re-audit regularly - debt grows; quarterly audits prevent accumulation