/ralph — RALF Iteration Loop
Standalone Read-Act-Learn-Feedback loop. Iterate any task until a mechanically-verifiable success signal triggers, or a kill-on signal halts the loop. Caps prevent runaway cost.
When to use
- "Write code until
cargo test exits 0"
- "Generate test cases until rubric scores ≥ 4.0"
- "Refactor until linter is clean"
- "Convert this YAML to JSON until schema validates"
Not for: open-ended exploration (use /spike), code where you'd rather review the plan first (use /plan then /develop), or anything without a binary success oracle.
Invocation
/ralph "<task>" --oracle <type:value> --kill-on <type:value> [--max-iterations N] [--token-budget N] [--time-cap-minutes N]
Examples:
/ralph "write a Rust CLI that parses CSV" --oracle cli:./test-cli.sh --kill-on oracle-pass
/ralph "generate 100 test cases for /develop rubric" --oracle judge:test-case-rubric.md --kill-on oracle-pass --max-iterations 8
/ralph "fix flaky test in src/api/login.test.ts" --oracle cli:./run-tests.sh --kill-on same-error-repeats:3
Required arguments
Both required — skill rejects invocation if either is missing per ralph-budget.md rule.
--oracle <type:value>
| Type |
Format |
Pass condition |
cli |
cli:./script.sh |
Exit 0 |
judge |
judge:rubric-name.md |
eval-judge agent score ≥ rubric threshold |
regex |
regex:./out.log:^DONE$ |
Pattern matches in named file |
python |
python:./check.py |
Exit 0 |
--kill-on <type:value>
| Type |
Format |
Trigger |
oracle-pass |
(no value) |
Happy stop on first oracle success |
same-error-repeats |
same-error-repeats:N |
Same error string N iterations in a row |
regex |
regex:PATTERN |
Pattern matches in latest model output |
python |
python:./kill.py |
Custom predicate exits 2 |
no-progress |
no-progress:N |
N iterations with no file diff |
Caps (defaults from userConfig)
| Cap |
Default |
userConfig override |
--max-iterations |
10 |
ralph_default_max_iter |
--token-budget |
200_000 |
ralph_default_token_budget |
--time-cap-minutes |
120 |
ralph_default_time_cap_minutes |
Session-aggregate caps from ralph-budget.md HIGH-3 also apply (20 iter / 400K tokens / 180 min across all RALF runs in one session).
State and logs
Every run writes to <repo>/.ai-skills-memory/ralph/<run-id>/:
config.json — caps + oracle + kill-on as locked at startactive.lock — presence = run is in progressinitial-prompt.md — full init prompt (G10)iter-NNN/ — one dir per iteration: prompt.md, output.md, diff.patch, oracle-result.json, tokens.jsonbudget.json — final totals on exit
Per-iteration tokens.json (v0.1.6) records tokens spent that iteration plus runaway: true when a single iteration exceeds 3× the fair share (token_budget / max_iterations). Runaway warnings also append to .ai-skills-memory/ralph-warnings.log.
Init vs continuation prompts
- Iter 1 (init): full task brief — goal, constraints, evidence, output contract, oracle definition, kill-on signal. Typically 5–15K tokens
- Iter ≥ 2 (continuation): state delta only — last-iter diff + oracle failure summary + top-3 active constraints + kill-on countdown. Typically 1–3K tokens (~70% savings)
Continuation template at ${CLAUDE_PLUGIN_ROOT}/skills/ralph/templates/continuation-prompt.md — applied automatically by ralph-stop.py hook.
Memory writes
| Layer |
When |
Shape |
| L4 |
RALF terminal state |
.ai-skills-memory/ralph/<run-id>/budget.json (iterations, tokens, exit reason) |
| L4 |
After kill or oracle-pass |
.ai-skills-memory/ralph-history.jsonl summary line |
Failure modes
- Missing
--oracle or --kill-on: rejected at arg validation with clear error
- Oracle script crashes (exit ≠ 0 AND ≠ 2): treated as
ORACLE_ERROR, loop killed, diagnostic surfaced
- Hard cap hit: soft warn at threshold, hard pause at cap, user prompted to confirm continuation, raise budget, or abort
- Buggy
ralph-stop.py hook: hook fails open per failure-recovery.md; never blocks Stop
Integration
- Hooks:
ralph-stop.py (Stop event) drives the loop, writes per-iter state, enforces budgets; ralph-iter-meter.py (PostToolUse, v0.1.6) estimates per-iter token spend
- Rule:
ralph-budget.md (caps, oracle/kill-on contract, failure modes)
- Schemas:
plugin/schemas/spawn-payload.schema.json if RALF spawns subagents
- Templates:
plugin/skills/ralph/templates/continuation-prompt.md (G10)
- Used by:
/feature-design, /develop, /bugfix, /refactor, /migrate for embedded RALF segments
1---2name: ralph3description: Use this skill when iterating a task until a binary success condition holds (test passes, schema validates, output matches a regex) and a power user wants a standalone RALF (Read-Act-Learn-Feedback) iteration loop — to wrap the task in a feedback loop with a mechanically-verifiable oracle and a kill-on signal. Not for open-ended exploration — use /spike for that.4context: fork5argument-hint: "<task description>"6---78# /ralph — RALF Iteration Loop910Standalone Read-Act-Learn-Feedback loop. Iterate any task until a mechanically-verifiable success signal triggers, or a kill-on signal halts the loop. Caps prevent runaway cost.1112## When to use1314- "Write code until `cargo test` exits 0"15- "Generate test cases until rubric scores ≥ 4.0"16- "Refactor until linter is clean"17- "Convert this YAML to JSON until schema validates"1819**Not for:** open-ended exploration (use `/spike`), code where you'd rather review the plan first (use `/plan` then `/develop`), or anything without a binary success oracle.2021## Invocation2223```24/ralph "<task>" --oracle <type:value> --kill-on <type:value> [--max-iterations N] [--token-budget N] [--time-cap-minutes N]25```2627Examples:28```29/ralph "write a Rust CLI that parses CSV" --oracle cli:./test-cli.sh --kill-on oracle-pass30/ralph "generate 100 test cases for /develop rubric" --oracle judge:test-case-rubric.md --kill-on oracle-pass --max-iterations 831/ralph "fix flaky test in src/api/login.test.ts" --oracle cli:./run-tests.sh --kill-on same-error-repeats:332```3334## Required arguments3536Both required — skill rejects invocation if either is missing per `ralph-budget.md` rule.3738### `--oracle <type:value>`3940| Type | Format | Pass condition |41|---|---|---|42| `cli` | `cli:./script.sh` | Exit 0 |43| `judge` | `judge:rubric-name.md` | `eval-judge` agent score ≥ rubric threshold |44| `regex` | `regex:./out.log:^DONE$` | Pattern matches in named file |45| `python` | `python:./check.py` | Exit 0 |4647### `--kill-on <type:value>`4849| Type | Format | Trigger |50|---|---|---|51| `oracle-pass` | (no value) | Happy stop on first oracle success |52| `same-error-repeats` | `same-error-repeats:N` | Same error string N iterations in a row |53| `regex` | `regex:PATTERN` | Pattern matches in latest model output |54| `python` | `python:./kill.py` | Custom predicate exits 2 |55| `no-progress` | `no-progress:N` | N iterations with no file diff |5657## Caps (defaults from `userConfig`)5859| Cap | Default | userConfig override |60|---|---|---|61| `--max-iterations` | 10 | `ralph_default_max_iter` |62| `--token-budget` | 200_000 | `ralph_default_token_budget` |63| `--time-cap-minutes` | 120 | `ralph_default_time_cap_minutes` |6465Session-aggregate caps from `ralph-budget.md` HIGH-3 also apply (20 iter / 400K tokens / 180 min across all RALF runs in one session).6667## State and logs6869Every run writes to `<repo>/.ai-skills-memory/ralph/<run-id>/`:70- `config.json` — caps + oracle + kill-on as locked at start71- `active.lock` — presence = run is in progress72- `initial-prompt.md` — full init prompt (G10)73- `iter-NNN/` — one dir per iteration: `prompt.md`, `output.md`, `diff.patch`, `oracle-result.json`, `tokens.json`74- `budget.json` — final totals on exit7576Per-iteration `tokens.json` (v0.1.6) records `tokens` spent that iteration plus `runaway: true` when a single iteration exceeds 3× the fair share (`token_budget / max_iterations`). Runaway warnings also append to `.ai-skills-memory/ralph-warnings.log`.7778## Init vs continuation prompts7980- **Iter 1 (init):** full task brief — goal, constraints, evidence, output contract, oracle definition, kill-on signal. Typically 5–15K tokens81- **Iter ≥ 2 (continuation):** state delta only — last-iter diff + oracle failure summary + top-3 active constraints + kill-on countdown. Typically 1–3K tokens (~70% savings)8283Continuation template at `${CLAUDE_PLUGIN_ROOT}/skills/ralph/templates/continuation-prompt.md` — applied automatically by `ralph-stop.py` hook.8485## Memory writes8687| Layer | When | Shape |88|---|---|---|89| L4 | RALF terminal state | `.ai-skills-memory/ralph/<run-id>/budget.json` (iterations, tokens, exit reason) |90| L4 | After kill or oracle-pass | `.ai-skills-memory/ralph-history.jsonl` summary line |9192## Failure modes9394- **Missing `--oracle` or `--kill-on`:** rejected at arg validation with clear error95- **Oracle script crashes (exit ≠ 0 AND ≠ 2):** treated as `ORACLE_ERROR`, loop killed, diagnostic surfaced96- **Hard cap hit:** soft warn at threshold, hard pause at cap, user prompted to confirm continuation, raise budget, or abort97- **Buggy `ralph-stop.py` hook:** hook fails open per `failure-recovery.md`; never blocks Stop9899## Integration100101- **Hooks**: `ralph-stop.py` (Stop event) drives the loop, writes per-iter state, enforces budgets; `ralph-iter-meter.py` (PostToolUse, v0.1.6) estimates per-iter token spend102- **Rule**: `ralph-budget.md` (caps, oracle/kill-on contract, failure modes)103- **Schemas**: `plugin/schemas/spawn-payload.schema.json` if RALF spawns subagents104- **Templates**: `plugin/skills/ralph/templates/continuation-prompt.md` (G10)105- **Used by**: `/feature-design`, `/develop`, `/bugfix`, `/refactor`, `/migrate` for embedded RALF segments
avav25