Argument	Scan Scope
`all`	Full codebase
`challenges`	`lib/heads_up/challenges`, `lib/heads_up_web/live/challenge_live/`
`goals`	`lib/heads_up/goals`, `lib/heads_up_web/live/goal_live/`
`users`	`lib/heads_up/accounts`, `lib/heads_up_web/live/users_live/`
`social`	Social features: likes, comments, subscriptions, feed
`admin`	`lib/heads_up_web/live/admin_live/*`
`tests`	`test/*/_test.exs`
`schemas`	`lib/heads_up/*/.ex` (Ecto schemas only)
`liveviews`	`lib/heads_up_web/live/*/.ex`

1.1 Code Debt Scan

Search for these patterns:

Duplicated Code

Grep for identical function bodies across files
Look for repeated query patterns in contexts
Find duplicated template/component markup
Identify copy-pasted event handlers in LiveViews

Complex Code

Functions longer than 50 lines
Deeply nested case/cond/if blocks (>3 levels)
LiveView render/1 functions over 200 lines
Context modules over 500 lines
Functions with more than 5 parameters

Poor Structure

Context functions that bypass the context pattern (direct Repo calls in LiveViews)
Missing ownership/authorization checks
Circular module dependencies
Business logic in templates/components

1.2 Architecture Debt Scan

Missing context boundaries (logic in wrong context)
Fat LiveViews (business logic in event handlers instead of contexts)
Missing PubSub for real-time features
Inconsistent error handling patterns
Missing or inconsistent API boundaries

1.3 Testing Debt Scan

Files with no corresponding test file
Context functions without test coverage
LiveView events without test coverage
Missing edge case tests (empty states, boundaries, errors)
Slow or flaky tests

1.4 Schema & Migration Debt

Missing indexes on foreign keys
Missing unique constraints
Inconsistent timestamp types (naive_datetime vs utc_datetime)
Missing on_delete specifications
Schema fields without validation in changeset

1.5 Documentation Debt

Public context functions without @doc
Missing @moduledoc on modules
Undocumented complex business rules
Missing typespec (@spec) on public functions

Phase 2: Impact Assessment

For each debt item found, assess:

Severity Levels:

Critical: Security risk, data integrity, production crashes
High: Bugs likely, significant dev time waste, performance degradation
Medium: Developer friction, maintenance burden, inconsistency
Low: Code style, minor inefficiency, cosmetic

Impact Scoring:

Impact = Frequency_of_change x Severity x Blast_radius

Where:
  Frequency: How often this code is touched (1-5)
  Severity: How bad the debt is (1-5)
  Blast_radius: How much code is affected (1-5)

Phase 3: Generate Report

Create the report at project/tech-debt/TD-[DATE]-[area].md

# Technical Debt Report: [Area]
**Date:** YYYY-MM-DD
**Scope:** [what was scanned]
**Overall Score:** X/100 (lower = more debt)

## Executive Summary
- Total debt items: X
- Critical: X | High: X | Medium: X | Low: X
- Estimated remediation effort: X hours
- Top 3 priorities: [list]

## Debt Inventory

### Critical Items
| # | Category | File | Description | Impact | Effort |
|---|----------|------|-------------|--------|--------|
| 1 | [type]   | path | description | score  | hours  |

### High Priority Items
[same table format]

### Medium Priority Items
[same table format]

### Low Priority Items
[same table format]

## Metrics

### Code Quality
- Average function length: X lines
- Functions >50 lines: X
- Modules >500 lines: X
- Duplicated patterns: X locations

### Test Coverage
- Context functions tested: X%
- LiveView events tested: X%
- Files without tests: X

### Schema Health
- Missing indexes: X
- Missing validations: X
- Inconsistent patterns: X

## Quick Wins (< 4 hours each)
1. [item] - Effort: Xh, Savings: Xh/month
2. [item] - Effort: Xh, Savings: Xh/month

## Remediation Roadmap

### Week 1-2: Quick Wins
- [ ] [task]
- [ ] [task]

### Month 1: High Priority
- [ ] [task]
- [ ] [task]

### Month 2-3: Medium Priority
- [ ] [task]
- [ ] [task]

## Prevention Recommendations
1. [recommendation]
2. [recommendation]

Phase 4: Create Tasks

For each Quick Win and High Priority item, create a task file:

Location: project/tech-debt/tasks/TDT-XXX-[slug].md

# TDT-XXX: [Task Title]

## Source
- Report: TD-[DATE]-[area].md
- Severity: [Critical/High/Medium/Low]
- Impact Score: X/125

## Description
[What needs to change and why]

## Files Affected
- `path/to/file.ex`

## Steps
1. [step]
2. [step]
3. [step]

## Effort Estimate
- Hours: X
- Complexity: [Low/Medium/High]

## Acceptance Criteria
- [ ] [criterion]
- [ ] [criterion]
- [ ] Tests pass: `mix test`

## Status
- [ ] Planned
- [ ] In Progress
- [ ] Done
- [ ] Verified

Elixir/Phoenix Specific Checks

Context Pattern Violations

# BAD: Repo call in LiveView
def handle_event("save", params, socket) do
  Repo.insert(changeset)  # Should be in context
end

# GOOD: Context function
def handle_event("save", params, socket) do
  Goals.create_goal(params)
end

LiveView Anti-patterns

# BAD: Business logic in template
<%= if length(user.goals) >= 2 do %>  # Magic number, logic in template

# GOOD: Helper or context function
<%= if Goals.at_limit?(@current_user) do %>

Schema Checks

# Check for: missing validates, missing indexes, missing on_delete
schema "goals" do
  belongs_to :user, User  # Should have on_delete
  field :status, Ecto.Enum  # Should validate in changeset
end

Query Performance

# BAD: N+1 query
goals |> Enum.map(fn g -> Repo.preload(g, :user) end)

# GOOD: Batch preload
goals |> Repo.preload(:user)

Output

After generating the report, display a summary:

Tech Debt Analysis Complete
============================
Scope: [area]
Report: project/tech-debt/TD-[DATE]-[area].md
Tasks: X created in project/tech-debt/tasks/

Summary:
  Critical: X items
  High:     X items
  Medium:   X items
  Low:      X items
  Total:    X items

Top 3 Quick Wins:
  1. [description] (Xh effort, Xh/month savings)
  2. [description] (Xh effort, Xh/month savings)
  3. [description] (Xh effort, Xh/month savings)

Estimated total remediation: X hours

tech-debt

Technical Debt Analysis and Remediation

Workflow

Phase 1: Scan & Inventory