10.6ADR-006: Error Recovery Strategy

Context

When a command fails (stale ref, timeout, unexpected state), the agent needs a strategy.

Decision

Three-tier recovery:

Tier 1: Re-snapshot and Re-resolve (Agent Reasoning)

Agent: playwright-cli click e5 → ERROR: ref not found
Agent: "The ref is stale — the page must have changed. Fresh snapshot."
Agent: playwright-cli snapshot
Agent: *reads YAML: button "Submit Form" [ref=e9]*
Agent: playwright-cli click e9 → SUCCESS

Tier 2: Screenshot Analysis

Agent: playwright-cli screenshot
Agent: *reads the PNG*
Agent: "I see a loading spinner. The page hasn't finished loading."
Agent: *waits, re-snapshots — spinner gone, refs present*
Agent: playwright-cli click e9 → SUCCESS

Tier 3: Escalate to the Healer Workflow

Agent: "Recovery inside the run hasn't worked. This is a test-maintenance
problem, not a retry problem."
→ Hand the failing test to Playwright's healer agent: it replays the failure,
  inspects the live UI, patches locators/waits/data and reruns — or concludes
  the functionality itself is broken and reports a bug instead of a green test.

Consequences

• (+) Most failures resolve at Tier 1 (one snapshot read — cheap)
• (+) Tier 2 provides visual debugging even for automated runs
• (+) Tier 3 turns persistent failures into either a durable test fix or a real bug report — never a silently forced pass
• (-) Multi-tier recovery adds latency to failure cases