---
name: ralph-loop
description: "Run a bounded iterative execution loop that repeatedly works, tests, and fixes a clearly-defined task until an explicit completion condition holds or a maximum iteration count is reached. Use for /ralph-loop, 'start a ralph loop', 'iterate until', 'get all tests passing', 'complete this migration', or 'keep testing and fixing until X'. Always bounded; never runs unlimited."
license: MIT
metadata:
  adapted-from: "cursor/plugins/ralph-loop"
  version: "1.0.0"
---

# Ralph Loop (bounded iterative execution)

Drive a clearly-defined task to completion by iterating: work, verify, and if not done yet, repeat with the same objective while seeing the previous iteration's results. Each iteration builds on the real state of the files and tests from the last one.

## Safety rules (non-negotiable)
- **Every loop has a maximum iteration limit.** Default `max_iterations: 10`. Never run unlimited. If the user asks for "unlimited" or "until done" with no cap, still apply a cap (default 10, or a higher explicit number they name) and tell them the cap you set.
- **Every loop has an explicit completion condition.** A checkable predicate, for example "all tests in `foo/` pass", "`npm run build` exits 0", or the acceptance criteria the user stated. If the task has no checkable predicate, do NOT start a loop — this task needs the **poteto-mode** workflow or a human decision instead.
- **Do not use Ralph for ambiguous tasks** that require human product or design decisions. Ralph is for well-defined, verifiable objectives (get tests green, finish a migration, implement against explicit acceptance criteria, repeatedly test/fix a defined issue).
- **Respect always-pause boundaries** every iteration: no deploys, data deletion, force-push, or external messages without explicit approval. Never auto-commit or auto-push.

## Setup
1. Gather from the user:
   - The **task prompt** (what to accomplish).
   - **completion condition** (the exact predicate that means "done"). Required.
   - **max_iterations** (integer, default 10).
2. Write the state file at `.ralph/scratchpad.md` in the working directory (create `.ralph/` if needed), for persistence and resumability:
   ```markdown
   ---
   iteration: 1
   max_iterations: 10
   completion_condition: "<the exact checkable predicate>"
   status: active
   ---

   <the task prompt goes here>
   ```
   Quote the `completion_condition` value if it contains special characters.
3. Confirm to the user: the task, the cap, and the completion condition. Then begin.

## Iteration loop
Repeat, tracking the iteration count against `max_iterations`:
1. **Work** on the task, using the real current state of the files/tests (do not restart from scratch each time; build on prior progress).
2. **Verify** against the completion condition. Run the actual check (tests, build, acceptance script) and read the real result.
3. **Decide:**
   - If the completion condition is genuinely and verifiably met -> set `status: complete` in the state file, report success with the evidence, and stop. Never claim completion without running the check.
   - If not met and `iteration < max_iterations` -> increment `iteration` in the state file, record a one-line note on what changed and what is still failing, and continue to the next iteration.
   - If `iteration >= max_iterations` -> stop. Set `status: max-iterations-reached`. Report progress, what still fails, and the recommended next step. Do NOT silently continue past the cap.
4. Persist the updated `iteration` and note to the state file each pass so the loop is resumable and auditable.

## Completion
On success, report the completion condition, the check you ran, and its passing output. On hitting the cap, report how far you got, the remaining failures, and a concrete recommendation. Then clear or leave the state file per the user's preference (the **cancel-ralph** skill removes it).

## Kiro adaptation
Cursor implemented the re-feed via a `stop` shell hook that intercepted each turn end and fed the prompt back (`[Ralph loop iteration N.]`), with `max_iterations: 0` meaning unlimited. Kiro Web has no reliable post-turn re-feed hook, and unlimited iteration is unsafe, so this port makes the agent **self-drive the bounded loop** within its execution, checking the predicate and the iteration cap each pass. The default cap is changed from unlimited to 10. The state file (`.ralph/scratchpad.md`) preserves iteration/cap/condition for persistence and resumability. See the power's `INSTALL.md` for the optional best-effort hook and its limits. Reference: the Ralph technique by Geoffrey Huntley (https://ghuntley.com/ralph/).