mochammadshenna/go-adk-q/tech-debt

Tech Debt Management

Systematically identify, categorize, and prioritize technical debt.

Debt categories

Prioritization framework

Score each debt item on three dimensions (1-5 scale):

• Impact: How much does it slow the team down or risk breakage?
• Risk: What's the cost of NOT fixing it?
• Effort: How hard is the fix? (Lower effort = higher priority, so invert this)

Priority score = (Impact + Risk) × (6 − Effort)

High-priority items: high impact + high risk + low effort. These pay for themselves quickly.

Identification process

For code debt

# Find long functions (>50 lines is a smell)
grep -n "^func " cmd/tui/chat.go | head -20
 
# Find duplicated error handling patterns
grep -rn "if err != nil" . --include="*.go" | wc -l
 
# Find TODO/FIXME/HACK markers
grep -rn "TODO\|FIXME\|HACK" . --include="*.go"

For test debt

go test -coverprofile=cover.out ./...
go tool cover -func=cover.out | tail -1  # total coverage

For dependency debt

go list -m -u all 2>/dev/null | grep '\['  # modules with available updates

Output format

## Tech Debt Audit — [Date]
 
### Summary
Total items: N | Critical: N | High: N | Medium: N | Low: N
 
### Critical (fix before next release)
| Item | Type | Impact | Risk | Effort | Score |
|------|------|--------|------|--------|-------|
| [description] | code | 5 | 5 | 2 | 40 |
 
### High priority
[same table]
 
### Remediation plan
Phase 1 (this sprint): [specific items]
Phase 2 (next sprint): [specific items]
Phase 3 (backlog): [remaining items]
 
### What NOT to fix
[Items that are too costly relative to benefit]

Communicating debt to stakeholders

Translate technical debt into business terms:

• Code debt: "This function is 800 lines long. Every bug fix takes 3x longer than it should and risks introducing regressions."
• Test debt: "We have 40% test coverage. When we shipped the last release, 3 bugs made it to production that tests would have caught."
• Dependency debt: "We're 2 major versions behind on our auth library. Known CVEs affect our current version."

Make the cost of NOT fixing it concrete.