report-debt

name	report-debt
description	Generate comprehensive tech debt assessment with quantified metrics and prioritized issues. Use for sprint planning, stakeholder reports, or justifying refactoring time allocation.

Report Debt

Generate a comprehensive technical debt assessment with quantified metrics, prioritized issues, and actionable recommendations.

Prerequisites

Omen CLI must be installed and available in PATH.

Workflow

Step 1: Scan for Self-Admitted Debt

Run the SATD analysis to find explicit debt markers:

omen -f json satd

Captures TODO, FIXME, HACK, XXX, and other debt markers with severity.

Step 2: Calculate TDG Scores

Run the TDG analysis for quality grades:

omen -f json tdg

TDG provides A-F grades based on complexity, churn, and health metrics.

Step 3: Measure Duplication

Run the clone detection analysis:

omen -f json clones

Calculate duplication ratio and identify clone clusters.

Step 4: Assess Defect Risk

Run the defect prediction analysis:

omen -f json defect

Identify files with high predicted defect probability.

Step 5: Check Complexity

Run the complexity analysis:

omen -f json complexity

Find functions exceeding complexity thresholds.

Debt Categories

Organize findings by category:

Category	Source	Impact
Explicit	SATD markers	Known issues, documented
Structural	TDG grade D/F	Hard to maintain
Duplication	Clone ratio > 5%	Maintenance burden
Risk	Defect probability > 0.7	Likely to cause bugs
Complexity	Cyclomatic > 15	Hard to test/modify

Output Format

Generate a stakeholder-ready report:

# Technical Debt Report
Generated: YYYY-MM-DD

## Executive Summary

| Metric | Value | Status |
|--------|-------|--------|
| Overall TDG Grade | C+ | Needs attention |
| Duplication Ratio | 7.2% | Above target (5%) |
| High-Risk Files | 12 | 8% of codebase |
| SATD Items | 45 | 12 critical |

## Debt by Category

### Explicit Debt (SATD)
- **Critical**: 12 items (FIXME, HACK)
- **High**: 18 items (TODO with urgency)
- **Normal**: 15 items (TODO)

Top items:
1. `payment/processor.go:45` - HACK: Temporary fix for race condition
2. `auth/session.go:123` - FIXME: Security review needed
3. ...

### Structural Debt (TDG Grades)
| Grade | Files | % of Codebase |
|-------|-------|---------------|
| A | 45 | 30% |
| B | 52 | 35% |
| C | 32 | 21% |
| D | 15 | 10% |
| F | 6 | 4% |

Worst files:
1. `legacy/importer.go` - Grade F (TDG: 18)
2. `core/processor.go` - Grade D (TDG: 35)

### Duplication Debt
- **Total clones**: 23 clone groups
- **Duplicated lines**: 1,245 (7.2% of codebase)

Largest clones:
1. 85 lines duplicated across 3 files in `handlers/`
2. 45 lines duplicated between `validator.go` and `checker.go`

### Risk Debt
- **High-risk files**: 12 (defect probability > 0.7)
- **Medium-risk files**: 28 (probability 0.5-0.7)

## Recommended Actions

### Sprint 1 (Quick Wins)
1. Address 12 critical SATD items (est: 8 hours)
2. Consolidate largest clone cluster (est: 4 hours)
3. Split `legacy/importer.go` (est: 6 hours)

### Sprint 2-3 (Structural)
1. Refactor Grade D files (est: 20 hours)
2. Reduce complexity in `core/processor.go` (est: 8 hours)

### Long Term
1. Eliminate all Grade F files
2. Reduce duplication to < 3%
3. Add tests to high-risk files

## Tracking

| Metric | Last Month | This Month | Trend |
|--------|------------|------------|-------|
| TDG Average | 62 | 58 | Improving |
| Duplication | 8.1% | 7.2% | Improving |
| SATD Critical | 15 | 12 | Improving |