# Error Recovery

## Verification Rules

Verification is tiered to balance speed and safety:

**Per-task** (after each task):

| Change Type | Verification Steps |
|-------------|-------------------|
| Any .ex/.exs | `mix format` + `mix compile --warnings-as-errors` |
| Schema/migration | Above + `mix ecto.migrate` (dev) |

**Per-phase** (after all tasks in a phase):

| Scope | Verification Steps |
|-------|-------------------|
| Always | `mix compile --warnings-as-errors` |
| Always | `mix test <affected_test_files>` |
| Always | `mix credo --strict` |

**Final gate** (after all phases): `mix test` (full suite)

## When Verification Fails

1. **Compile error**: Read error, fix, retry
2. **Test failure**: Analyze failure, fix code or test
3. **Credo warning**: Auto-fix if possible, else flag
4. **After 3 retries**: Log blocker, skip task, continue

## BLOCKER Format

```markdown
## BLOCKER: Task could not be completed

**Task ID**: P2-T3
**Task**: Implement register_user/1
**Attempts**: 3
**Last Error**: Test assertion failed - expected {:ok, user} got {:error, changeset}
**Files**: lib/my_app/accounts.ex:45

**Action Required**: Human review needed
**Resume**: `/phx:work plan.md --from P2-T3`
```

**Also write a DEAD-END entry** to the scratchpad so future
sessions don't re-try the same failed approach:

```markdown
### [HH:MM] DEAD-END: {task description}
Tried: {approach attempted}. Failed because: {root cause}.
Attempts: 3. See BLOCKER in progress.md for full error.
```

Append to `.claude/plans/{slug}/scratchpad.md`.

## Recovery After BLOCKER

When user resolves a blocker and resumes:

1. Re-read the plan file for current checkbox state
2. Start from the previously blocked task
3. Verify the fix compiles and tests pass
4. Mark checkbox and continue

# Execution Guide

Step-by-step execution details for `/phx:work`.

## Contents

- [Loading a Plan](#loading-a-plan)
- [Task Routing](#task-routing)
- [Parallel Task Execution](#parallel-task-execution)
- [Verification](#verification)
- [Proactive Patterns](#proactive-patterns)
- [Checkpoint Pattern](#checkpoint-pattern)
- [Phase Transitions](#phase-transitions)
- [Git Integration](#git-integration)
- [Error Recovery](#error-recovery)

## Loading a Plan

Read the plan file and count progress:

```markdown
## Phase 1: Schema Design [COMPLETED]
- [x] [P1-T1][ecto] Create users migration
- [x] [P1-T2][ecto] Add indexes

## Phase 2: Context Module [IN_PROGRESS]
- [x] [P2-T1][direct] Generate context with mix phx.gen.context
- [ ] [P2-T2][ecto] Add password_hash field    <-- NEXT TASK
- [ ] [P2-T3][direct] Implement register_user/1
```

**Task ID format**: `[Pn-Tm]` where n=phase, m=task number.

With `--from P2-T3`: Skip directly to that task.

## Task Routing

### Primary: Parse Agent Annotation

Task format: `- [ ] [Pn-Tm][agent] Description`

```markdown
- [ ] [P2-T2][ecto] Add password_hash field to schema
                ^^^^
           Parse this annotation -> spawn ecto-schema-designer
```

### Routing Table

| Annotation | Agent | Verification |
|------------|-------|--------------|
| `[ecto]` | ecto-schema-designer | migrate + test |
| `[liveview]` | liveview-architect | test + browser |
| `[oban]` | oban-specialist | test + manual |
| `[otp]` | otp-advisor | test |
| `[security]` | security-analyzer | test + audit |
| `[test]` | testing-reviewer | test only |
| `[direct]` | (none) | compile + format |

### Fallback: Keyword Matching (Legacy Plans)

If no `[agent]` annotation, fall back to keywords:

| Keywords (priority order) | Agent |
|---------------------------|-------|
| auth, login, password, token, permission | security-analyzer |
| schema, migration, field, changeset | ecto-schema-designer |
| worker, job, queue, oban | oban-specialist |
| genserver, supervisor, process | otp-advisor |
| liveview, component, mount | liveview-architect |
| test, assert, mock | testing-reviewer |
| (no match) | (direct execution) |

**Security priority**: Security keywords ALWAYS win, even if other
patterns match.

### `[direct]` Task Guidance

Tasks annotated `[direct]` are simple and don't need a specialist:

- **Config changes**: Adding env vars, updating `config/runtime.exs`
- **Dependencies**: Adding libraries to `mix.exs`, running `mix deps.get`
- **Scaffolding**: Creating directory structure, empty modules
- **Simple wiring**: Adding routes, imports, aliases
- **File operations**: Moving, renaming, or deleting files

Implement these directly without spawning a Task agent. Run
verification (compile + format) after each one.

## Parallel Task Execution

Tasks under `### Parallel:` header execute via subagents:

### Detection

```markdown
## Phase 2: Forms [IN_PROGRESS]

### Parallel: Deal Forms
- [ ] [P2-T1][direct] Add selectors to occupier deal form
- [ ] [P2-T2][direct] Add selectors to landlord deal form
- [ ] [P2-T3][direct] Add selectors to seller deal form

### Sequential
- [ ] [P2-T4][direct] Update shared form helpers
```

Tasks are parallelizable if they:

- Are under a `### Parallel:` header
- Modify different files (check Locations in task description)
- Don't share mutable state (schemas, helpers)

### Spawning Pattern

Spawn ALL parallel tasks in ONE message using the Agent tool:

```
Agent({
  subagent_type: "general-purpose",
  prompt: "Implement P2-T1: Add currency/area unit selectors to
    occupier deal form at lib/.../occupier_deal/.../details_form.ex.
    [full task context here]",
  run_in_background: true
})
Agent({
  subagent_type: "general-purpose",
  prompt: "Implement P2-T2: Add selectors to landlord deal form...",
  run_in_background: true
})
// ... one per parallel task
```

### Waiting and Checkpoint

After spawning, wait for ALL agents to complete, then run phase checkpoint:

```bash
mix format lib/**/*.ex lib/**/*.exs
mix compile --warnings-as-errors
mix test <affected_test_files>
mix credo --strict
```

Mark all completed task checkboxes in the plan.

### When NOT to Parallelize

- Tasks that edit the same file
- Tasks that depend on each other's output
- Schema/migration tasks (compilation lock)
- Tasks with `[security]` annotation (need careful review)

## Verification

### After Each Task

```bash
mix format --check-formatted <changed_files>
mix compile --warnings-as-errors
```

When Tidewave is available, also call
`mcp__tidewave__get_logs level: :error` after code changes to catch
runtime errors invisible to static analysis (supervision tree
failures, config errors, module loading problems).

### After Each Phase (Full)

```bash
mix compile --warnings-as-errors
mix test <affected_test_files>
mix credo --strict
```

### Per-Feature Behavioral Smoke Test (Tidewave)

After completing a feature (all phases for a domain), use
`project_eval` to verify end-to-end behavior. Pick the smoke
test by task annotation:

| Annotation | Smoke Test Pattern |
|------------|-------------------|
| `[ecto]` | `project_eval`: Create record -> fetch -> verify fields match |
| `[liveview]` | `get_logs level: :error` after navigation to the new route |
| `[oban]` | `project_eval`: Enqueue job -> check `oban_jobs` table for state |
| `[security]` | `project_eval`: Test unauthenticated access returns error |
| `[direct]` | `get_logs level: :error` to verify no regressions |

Use `project_eval` with transaction + rollback to verify without
persisting data. This catches issues unit tests miss: association
loading, default values, database constraints, and trigger behavior.

### After ALL Phases (Final Gate)

```bash
mix test  # full suite
```

### Elixir-Specific Verification

After each task, also run domain-appropriate checks:

| After | Extra Verification |
|-------|-------------------|
| `[ecto]` task | Verify migration safety, check `^` pinning |
| `[liveview]` task | Verify `connected?` check, stream usage for lists |
| `[oban]` task | Verify idempotency, string keys, no structs in args |
| `[security]` task | Verify authorization in every handle_event |

If verification fails, fix the issue and re-verify. After 3 failed
attempts, create a BLOCKER (see error-recovery.md).

## Proactive Patterns

### Factory Updates for Required Fields

When a task adds fields to `@required_fields`, BEFORE running tests:
grep for all factories/fixtures that build the affected struct
(`build(:X`, `insert(:X`, `def X_factory`), add new required fields
with sensible defaults to EVERY factory, THEN run the test suite.
Prevents cascading test failures from missing factory fields.

### Module Existence Check

When a plan says "create new module" or "extract to new module":

1. FIRST check if the module already exists:

   ```bash
   grep -rn "defmodule MyApp.ModuleName" lib/
   ```

2. If it exists, add to the existing module instead of creating a
   duplicate file (causes compilation errors from duplicate definitions)

## Checkpoint Pattern

After each task passes verification:

1. **Update plan**: Mark checkbox `- [x] [Pn-Tm]...` and **append
   implementation note** — key decisions, gotchas, actual values.
   Example: `- [x] [P2-T2] Add password_hash — used Bcrypt, 12 rounds, added virtual :password`
   These notes survive context compaction since the plan is re-read on resume.
2. **Complete Claude Code task** (only if `TaskUpdate` is in your tool list):
   `TaskUpdate({taskId, status: "completed"})` updates the UI progress indicator.
3. **Update phase status**: If all tasks done, change to `[COMPLETED]`
4. **Log progress**: Append to `.claude/plans/{feature}/progress.md`
5. **Start next task**: `TaskUpdate({nextTaskId, status: "in_progress"})` if
   available, then move to the next unchecked task

### Progress Log Entry

```markdown
## 14:32 - Task Completed [P2-T2]

**Task**: Add password_hash field to schema
**Files Modified**: lib/my_app/accounts/user.ex, priv/repo/migrations/xxx.exs
**Verification**: PASS (compile, format, credo, test)
```

## Phase Transitions

**Auto-continue between phases.** When all tasks in a phase
complete, mark it `[COMPLETED]` and start the next phase in the same
turn — the user approved the whole plan, so there is nothing to ask.
Keep going until all phases are done or a BLOCKER is hit.

```markdown
# Before
## Phase 1: Schema Design [IN_PROGRESS]
- [x] [P1-T1] Create users migration
- [x] [P1-T2] Add indexes
- [x] [P1-T3] Create schema module

# After
## Phase 1: Schema Design [COMPLETED]
- [x] [P1-T1] Create users migration — citext for email, added password_hash binary field
- [x] [P1-T2] Add indexes — unique on email, composite on [user_id, status]
- [x] [P1-T3] Create schema module — used virtual :password field with redact: true

## Phase 2: Context Module [IN_PROGRESS]  <-- Auto-start immediately
```

## Git Integration

### Commit Strategy

Don't commit after every task. Instead:

1. **After each phase**: Offer to create commit with phase summary
2. **After blockers**: Commit working state before human intervention
3. **After completion**: Ask user about final commit

### Branch Strategy (for /phx:full)

```bash
git checkout -b feature/{feature-slug}
# ... phases execute ...
# On completion, ready for PR
```

## Error Recovery

### Auto-Fix (Common Errors)

| Error Pattern | Auto-Fix |
|--------------|----------|
| `mix format` diff | Run `mix format` |
| Unused variable | Prefix with `_` |
| Missing import | Add import statement |

### Retry with Context

If first attempt fails, retry with error context in the prompt.

### Escalate to BLOCKER

After 3 failures, create blocker in progress file:

```markdown
## BLOCKER

**Task ID**: P2-T3
**Description**: Implement register_user/1
**Attempts**: 3

**Error History**:
1. Compile error: undefined function hash_password/1
2. Test failure: expected {:ok, _} got {:error, changeset}
3. Test failure: changeset errors [:email, "has already been taken"]

**Suggested Actions**:
- Review test setup (database not cleaned?)
- Check hash_password/1 implementation
- Verify unique constraint handling

**Resume**: `/phx:work plan.md --from P2-T3`
```

# Plan & Progress File Formats

## Plan File Format

Plans must follow this structure for parsing:

```markdown
# Plan: {Feature Name}

**Status**: IN_PROGRESS
**Created**: {date}
**Last Updated**: {date}

## Phase 1: {Phase Name} [COMPLETED|IN_PROGRESS|PENDING]

- [x] [P1-T1][ecto] Completed task description — implementation note (key decisions, gotchas)
- [ ] [P1-T2][ecto] Pending task description
- [ ] [P1-T3][direct] Another pending task

## Phase 2: {Phase Name} [PENDING]

### Parallel: {Group Name}

- [ ] [P2-T1][liveview] Task that can run in parallel
- [ ] [P2-T2][liveview] Another parallel task

### Sequential

- [ ] [P2-T3][security] Task that depends on above
```

**Task format**: `- [ ] [Pn-Tm][agent] Description`

- `[Pn-Tm]`: Phase n, Task m (for resume)
- `[agent]`: Agent annotation (for routing)

**Task ID format**: `[Pn-Tm]` - Phase n, Task m. Used for:

- Precise resume: `--from P2-T3`
- Blocker references
- Progress tracking

## Progress File Format

```markdown
# Progress: {Feature Name}

**Plan**: .claude/plans/{feature}/plan.md
**Started**: {date}
**Status**: IN_PROGRESS

## Session Log

### {date} {time}

**Task**: {description}
**Result**: PASS | FAIL
**Files**: {list of modified files}
**Notes**: {any observations}

---

### {date} {time}

**Task**: {description}
**Result**: FAIL
**Error**: {error message}
**Retry**: 1/3
**Resolution**: {what was tried}
```

# Harness Patterns for Error Recovery

Adapted from AutoHarness (Lou et al., 2026): programmatic verification
outperforms unstructured retry. A smaller model with good harnesses
beats a larger model without them.

## Critic-Refiner Pattern

When a task fails verification, use structured analysis instead of
immediate retry:

```
Attempt → Verify → FAIL
                    ↓
              Critic Phase (consolidate):
              - What EXACTLY failed? (first error only)
              - Is this the SAME error as before?
              - What has been tried already?
                    ↓
              Refiner Phase (targeted fix):
              - Address root cause from critic analysis
              - Don't repeat previous approaches
              - Check compound docs for known solutions
```

### When to Apply

- **Attempt 1**: Normal retry with error context
- **Attempt 2**: Pause. Compare errors. Same root cause = wrong mental model
- **Attempt 3**: Full critic analysis before BLOCKER decision

### Critic Analysis Template

Before the 3rd retry, consolidate:

```markdown
## Error Consolidation

**Command**: mix compile / mix test path:line
**Attempts**: 2 failed

**Error #1**: [exact error message]
**Error #2**: [exact error message]

**Same error?** Yes/No
- If YES → Root cause not addressed. Re-read source file.
- If NO → Progress made. New error is the real issue.

**Compound docs match?** grep -rl "KEYWORD" .claude/solutions/
**Dead-ends from scratchpad?** [any relevant entries]

**Next approach**: [specific, different from previous attempts]
```

## Action Verification Pattern

The plugin uses programmatic verification hooks (harness-as-action-verifier)
to catch invalid actions BEFORE they propagate:

| Hook | What It Verifies | Feedback On Failure |
|------|-----------------|---------------------|
| `format-elixir.sh` | Code formatting | "NEEDS FORMAT" warning |
| `iron-law-verifier.sh` | Iron Law violations in code content | Specific violation + line number |
| `security-reminder.sh` | Auth file patterns | Security Iron Laws checklist |
| `error-critic.sh` | Repeated mix failures | Consolidated error analysis |

Each hook follows the pattern:

1. **Propose** (Claude writes code)
2. **Verify** (hook checks programmatically)
3. **Reject with feedback** (specific violation message via stderr)
4. **Retry** (Claude fixes the specific issue)

This is more reliable than asking Claude to self-check because:

- grep-based checks never miss patterns
- Line numbers pinpoint exact locations
- Feedback is specific, not generic
- Verification runs every time (no skipping)

## Anti-Pattern: Unstructured Retry Loop

```
# BAD: Same approach, hope for different result
Attempt 1: mix test → FAIL
Attempt 2: tweak code → mix test → FAIL (same error)
Attempt 3: tweak more → mix test → FAIL (same error)
→ BLOCKER (wasted 3 attempts)
```

```
# GOOD: Critic-refiner with structured analysis
Attempt 1: mix test → FAIL
Attempt 2: compare errors → same root cause → re-read source
           → different fix approach → mix test → PASS
```

# Resume Strategies

## How State Works

**Plan checkboxes ARE the state.** No separate JSON state files.

- `[x]` = completed
- `[ ]` = pending
- Phase status `[COMPLETED|IN_PROGRESS|PENDING]` tracks phase progress
- BLOCKERs in progress file track failed tasks

## Resume Modes

### Default: Auto-detect

```
/phx:work  # Find most recent IN_PROGRESS plan, resume from first [ ]
```

### From Specific Task

```
/phx:work .claude/plans/auth/plan.md --from P2-T3
```

Skips directly to P2-T3 regardless of earlier unchecked tasks.

### Skip Blockers

```
/phx:work .claude/plans/auth/plan.md --skip-blockers
```

Continues past tasks that previously failed with BLOCKER status.

## Resume from Interrupted Session

On resume, the plan file itself shows progress:

```markdown
## Phase 1: Schema Design [COMPLETED]
- [x] [P1-T1][ecto] Create users migration
- [x] [P1-T2][ecto] Add indexes

## Phase 2: Context Module [IN_PROGRESS]
- [x] [P2-T1][direct] Generate context
- [ ] [P2-T2][ecto] Add password_hash     <-- Resumes here
- [ ] [P2-T3][direct] Implement register_user/1
```

No state file to parse. Just find first `[ ]` and continue.

## Consistency Check

On resume, validate:

- All tasks before the target should be `[x]` in plan
- If earlier tasks are unchecked, warn and ask user:
  - Skip them (mark as done)?
  - Go back and complete them?
  - Something else?

## Idempotent Task Execution

Tasks should be safe to re-execute:

| Task Type | Idempotent Approach |
|-----------|---------------------|
| Migration | Use `create_if_not_exists` or check schema |
| Schema | Write complete module, don't patch |
| Context | Write/replace function entirely |
| LiveView | Write complete component module |
| Test | Write complete test module |
| Route | Check route existence before adding |

If re-executing a task creates duplicate code, the task was not
idempotent. Write whole modules, not patches.