recovery

name: recovery description: Structured error recovery for failed or ineffective browser actions. when_to_use: When a tool returns an error, an action produces no visible effect, or page state diverges from expectation.

Recovery Skill

Structured recovery for browser automation failures. Covers execution errors, semantic failures, state divergence, tool limitations, and environmental blockers.

When to Use

Load this skill when any of these occur:

• A tool returns an error (is_error in tool result).
• A post-action screenshot shows no change or an unexpected change.
• A verification step (snapshot / verify) contradicts the expected state.
• An action succeeded but the effect is wrong (filled wrong field, clicked wrong element, upload didn't trigger, text truncated).
• An unexpected element blocks progress (modal, banner, CAPTCHA, cookie consent).

Recovery Loop

Follow three phases in order. Do not skip OBSERVE.

Step 1 — OBSERVE

Re-perceive the actual page state before making any recovery decision.

Batch these read-only tools in a single turn (the engine runs them concurrently):

• take_snapshot — current DOM / accessibility tree.
• take_screenshot — current visual state.
• list_console_messages — JS errors that may explain the failure.
• list_network_requests — failed API calls or unexpected redirects.

Before / after comparison: Compare the current state against what the page looked like before the failed action. Ask:

1. What changed? (anything at all — URL, DOM, visual layout)
2. What should have changed but didn't?
3. Are there new elements that weren't there before (modals, errors)?

Step 2 — DIAGNOSE

Classify the failure and assess progress.

Error classification — load the error-taxonomy reference for the full list: load_skill(skill_name="recovery", reference="error-taxonomy")

Key questions:

• Is this an execution error (tool reported failure) or a semantic error (tool succeeded but wrong effect)?
• Is the root cause a tool limitation, a wrong selector, a page state change, or an environmental blocker?

Progress assessment — did the action make any progress toward the goal?

• Partial progress (e.g. 3 of 5 fields filled): preserve what worked, recover only the failed part.
• Zero progress (nothing changed): the approach itself may be wrong; escalate sooner.
• Negative progress (broke something): undo if possible (evaluate_script({ code: "history.back()" }) or navigate to the previous URL), then re-observe.

Step 3 — RECOVER

Load the recovery-strategies reference for concrete playbooks: load_skill(skill_name="recovery", reference="recovery-strategies")

Escalation ladder — try in order, move to the next level when the current one fails:

1. Retry with modification — alternative selector, corrected input, adjusted timing.
2. Alternative approach — different tool (e.g. evaluate_script instead of MCP fill), different interaction pattern.
3. Replan — fundamentally different path to the same goal (e.g. direct URL navigation when menu path is broken).
4. Skip and record — preserve partial progress, log what failed and why, move to the next planned step.

After every recovery action, return to OBSERVE to verify the fix worked before continuing the plan.

Loop Control

• Per-step limit: max 2 recovery attempts on the same step before escalating to the next level.
• Cross-step pattern: same error pattern 3+ times across different steps → treat as systemic; skip and record.
• Replan depth: max 1 replan per original step. If the replanned approach also fails, skip.
• Fatal errors: never attempt recovery. Report and stop. Fatal types: PAGE_CRASHED, SESSION_EXPIRED, PERMISSION_DENIED, UNSUPPORTED_PAGE.
• After recovery: always continue the plan. One failed step does not end the entire task.

Available References

Load on demand: load_skill(skill_name="recovery", reference="<name>")

• error-taxonomy — 9 error categories with identification traits, causes, and recovery guidance
• recovery-strategies — concrete recovery playbooks with tool examples and escalation patterns
• verification-patterns — concrete verification examples with MCP tools (useful during OBSERVE phase for comprehensive state checks)