> ## 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.

# How It Works

> Understand the three-phase pipeline: Generate, Execute, and Self-heal.

## Overview

Refrain automates browser workflows through a three-phase pipeline:

1. **Generate** — AI explores your web app and builds a runbook.
2. **Execute** — The runbook replays deterministically with zero AI cost.
3. **Self-heal** — When UIs change, AI diagnoses failures and suggests fixes.

Each phase is independent. You generate once, execute unlimited times, and self-heal only when something breaks.

## Phase 1: Generate

The `generate` command takes a URL and a goal, then lets AI explore your web app to build a runbook.

<Steps>
  <Step title="AI opens the browser">
    Navigates to the start URL and takes a snapshot of the page.
  </Step>

  <Step title="AI explores the page">
    Decides which actions to take (click, input, navigate, etc.) based on the goal and page state. Each action is recorded as a step.
  </Step>

  <Step title="Stall detection">
    If AI gets stuck in a loop or makes no progress, it asks for human guidance. You can also intervene at any time during exploration.
  </Step>

  <Step title="AI reviews the steps">
    After reaching the goal, AI reviews all recorded steps — removing unnecessary ones and flagging risky actions that may need approval.
  </Step>

  <Step title="Runbook output">
    The final runbook is written as a structured file containing all steps, selectors, variables, and settings.
  </Step>
</Steps>

## Phase 2: Execute

The `execute` command replays a generated runbook. Selectors are resolved deterministically — **no AI tokens are consumed** on reruns (except when fallback features are triggered).

<Steps>
  <Step title="Load runbook and resolve variables">
    Variables are resolved from secrets, context, environment, or interactive prompts.
  </Step>

  <Step title="Execute each step">
    For each step, the executor resolves the selector using [multi-layered resolution](/concepts/selector-resolution), then performs the action (click, input, navigate, etc.).
  </Step>

  <Step title="Handle approvals">
    Steps marked as requiring approval pause execution and wait for human confirmation via CLI, Slack, Teams, or Discord.
  </Step>

  <Step title="Report results">
    A summary is printed showing success/failure for each step, with optional screenshots and notifications.
  </Step>
</Steps>

## Phase 3: Self-heal

When the target app's UI changes and steps start failing, `--self-heal` enables AI-powered diagnostics.

<Steps>
  <Step title="Enhanced execution">
    Self-heal mode enables aggressive retry strategies, selector caching, Agent Fallback, and Vision Fallback automatically.
  </Step>

  <Step title="Error classification">
    Each failure is classified into one of [6 categories](/concepts/error-classification) to guide the repair strategy.
  </Step>

  <Step title="AI repair suggestions">
    AI analyzes failed steps and generates two types of suggestions: runbook fixes (selector changes, step additions) and context fixes (updated page structure notes).
  </Step>

  <Step title="Apply fixes">
    Use the `fix-runbook` command to review and apply AI suggestions to your runbook.
  </Step>
</Steps>

## Key design principles

* **Reproducibility** — The same runbook produces the same result every time.
* **Zero rerun cost** — Deterministic execution means no AI tokens on reruns.
* **Human-in-the-loop** — Approval workflows keep humans in control of risky actions.
* **Self-maintaining** — AI auto-maintains runbooks when UIs change.

## What's next

<CardGroup cols={2}>
  <Card title="Generate a runbook" icon="wand-magic-sparkles" href="/guides/generate-runbook">
    Step-by-step guide for runbook generation.
  </Card>

  <Card title="Execute a runbook" icon="play" href="/guides/execute-runbook">
    How to run your generated runbook.
  </Card>

  <Card title="Self-heal mode" icon="wrench" href="/guides/self-heal">
    Diagnose and fix broken runbooks automatically.
  </Card>
</CardGroup>