---
name: ralph-loop-help
description: "Explain what the bounded Ralph loop is, how it works in Kiro, when to use it, and its safety limits. Use for /ralph-loop-help, 'how does ralph loop work', or 'help with the ralph loop'."
license: MIT
metadata:
  adapted-from: "cursor/plugins/ralph-loop/skills/ralph-loop-help"
  version: "1.0.0"
---

# Ralph Loop Help

## What it is
Ralph Loop is an iterative development technique (pioneered by Geoffrey Huntley, https://ghuntley.com/ralph/): the agent works toward the same objective repeatedly, seeing its own previous progress in the files and tests each pass, and iterating until the objective is verifiably met. In this Kiro port the loop is **agent-driven and always bounded**.

## How it works here
1. You give the agent a well-defined task, an explicit completion condition, and (optionally) a max iteration count.
2. The agent writes a state file at `.ralph/scratchpad.md` (task, iteration, cap, completion condition).
3. Each iteration the agent works, runs the real check for the completion condition, and reads the result.
4. It continues until the condition is verifiably met OR the iteration cap is reached, then stops and reports.

## Starting one
Ask, for example: "Start a ralph loop: get all tests in `src/api` passing. max 15 iterations." Options:
- **completion condition** (required) — the checkable predicate that means done.
- **max_iterations** (default 10) — hard cap; the loop never runs unlimited.

## Cancelling
Ask to cancel the ralph loop (the `cancel-ralph` skill removes the state file and reports the iteration count).

## Safety limits (Kiro port)
- Always bounded. Default cap is 10; there is no unlimited mode.
- Requires an explicit, checkable completion condition. No predicate -> no loop.
- Not for ambiguous tasks needing human product/design decisions.
- Never auto-commits, auto-pushes, deploys, or deletes data; always-pause boundaries hold every iteration.

## Good for
- Get all tests passing.
- Complete a migration with a clear done state.
- Implement a feature against explicit acceptance criteria.
- Repeatedly test and fix a clearly-defined issue.

## Not good for
- Tasks needing human judgment or design decisions.
- One-shot operations.
- Tasks with unclear or unverifiable success criteria.

## Difference from Cursor's original
Cursor re-fed the prompt via a background `stop` hook and defaulted to unlimited iterations. Kiro Web has no reliable re-feed hook and unlimited loops are unsafe, so the agent self-drives a bounded loop and the default is capped at 10.