> ## Documentation Index
> Fetch the complete documentation index at: https://docs.therefrain.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Self-Heal Mode

> Automatically diagnose failures and get AI repair suggestions when UIs change.

## Overview

When the target app's UI changes and runbook steps start failing, `--self-heal` mode runs the runbook with enhanced recovery features, classifies every failure, and generates AI-powered repair suggestions.

<Note>
  Self-heal mode requires [Team or higher](/concepts/plan-tiers).
</Note>

## How self-heal works

<Steps>
  <Step title="Run with --self-heal">
    ```bash theme={null}
    npx @refrainai/cli execute -- \
      --runbook ./login-flow.yaml \
      --context ./context.md \
      --secrets ./secrets.json \
      --self-heal
    ```
  </Step>

  <Step title="Enhanced recovery activates">
    Self-heal mode automatically enables several features that are off by default in normal execution, including selector cache, Agent Fallback, Vision Fallback, increased retries (5 instead of 3), and auto-approval of confirmation prompts. See the [comparison table below](#self-heal-vs-normal-execution) for a full breakdown.
  </Step>

  <Step title="Failures are classified">
    Each failed step is classified into one of [6 error categories](/concepts/error-classification). The category determines what kind of fix is most likely to resolve the issue.
  </Step>

  <Step title="AI generates repair suggestions">
    For each failure, AI generates two types of suggestions:

    * **Runbook fix** — Changes to the runbook itself (updated selectors, added steps, removed steps)
    * **Context fix** — Updates to `context.md` (new page structure notes, changed navigation paths)

    The error category is included in the AI prompt to improve suggestion accuracy.
  </Step>

  <Step title="Diagnostic report">
    A detailed report is generated with:

    * Per-step execution results and failure diagnostics
    * Error classification for each failure
    * AI repair suggestions
    * Recovery mechanism effectiveness statistics
  </Step>
</Steps>

## Self-heal vs normal execution

| Setting                |     Normal execution    | Self-heal mode |
| ---------------------- | :---------------------: | :------------: |
| `skipConfirmation`     |         `false`         |     `true`     |
| `enableSelectorCache`  |      plan-dependent     |     `true`     |
| `enableAgentFallback`  |      plan-dependent     |     `true`     |
| `enableVisionFallback` |      plan-dependent     |     `true`     |
| `maxRetries`           |            3            |        5       |
| Execution strategy     |         Standard        |   Aggressive   |
| AI repair suggestions  |            No           |       Yes      |
| Diagnostic report      | On request (`--report`) |     Always     |

## Applying fixes

After reviewing the self-heal report, use the `fix-runbook` command to apply the suggestions:

```bash theme={null}
npx @refrainai/cli fix-runbook -- \
  --runbook ./login-flow.yaml \
  --report ./login-flow-report.md
```

See [Apply fixes](/guides/fix-runbook) for the full workflow.

## Best practices

* **Run self-heal periodically** — Schedule regular self-heal runs to catch UI changes early, before they affect production workflows.
* **Version control your runbooks** — Keep runbooks in git so you can review and revert changes from fix-runbook.
* **Review before applying** — Always review AI suggestions before applying. The `fix-runbook` command shows a diff preview for each change.
* **Re-execute after fixing** — After applying fixes, run a normal execution to verify the runbook works correctly.

## What's next

<CardGroup cols={2}>
  <Card title="Apply fixes" icon="screwdriver-wrench" href="/guides/fix-runbook">
    Apply AI repair suggestions to your runbook.
  </Card>

  <Card title="Error classification" icon="triangle-exclamation" href="/concepts/error-classification">
    How failures are categorized.
  </Card>

  <Card title="Selector resolution" icon="crosshairs" href="/concepts/selector-resolution">
    How elements are found on the page.
  </Card>
</CardGroup>