Skip to main content

​
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.
Self-heal mode requires Team or higher.

​
How self-heal works

1

Run with --self-heal

npx @refrainai/cli execute -- \
  --runbook ./login-flow.yaml \
  --context ./context.md \
  --secrets ./secrets.json \
  --self-heal
2

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 for a full breakdown.
3

Failures are classified

Each failed step is classified into one of 6 error categories. The category determines what kind of fix is most likely to resolve the issue.
4

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

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

​
Self-heal vs normal execution

SettingNormal executionSelf-heal mode
skipConfirmationfalsetrue
enableSelectorCacheplan-dependenttrue
enableAgentFallbackplan-dependenttrue
enableVisionFallbackplan-dependenttrue
maxRetries35
Execution strategyStandardAggressive
AI repair suggestionsNoYes
Diagnostic reportOn request (--report)Always

​
Applying fixes

After reviewing the self-heal report, use the fix-runbook command to apply the suggestions: 
npx @refrainai/cli fix-runbook -- \
  --runbook ./login-flow.yaml \
  --report ./login-flow-report.md
See Apply fixes 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

Apply fixes

Apply AI repair suggestions to your runbook.

Error classification

How failures are categorized.

Selector resolution

How elements are found on the page.