/dev-ralph

name: dev-ralph
description: Persistence loop — keep working on a task until it's resolved or until a circuit breaker stops you. Different from /loop (which is time-based) — ralph is iteration-based with state.

Dev Ralph

Derived from oh-my-claudecode (MIT, Yeachan Heo). Adapted for the EvoNexus Engineering Layer.

Persistence loop. Keep iterating on a task until it's resolved, with a circuit breaker for safety. **Different from `/loop`** (which runs a prompt every N minutes) — ralph runs the same agent repeatedly until a goal is met.

Use When

• Task has a clear completion signal but unclear iteration count
• "Fix until tests pass" type work
• Auto-correcting loops where each iteration uses the previous result

Do Not Use When

• Time-based polling → use `/loop` (built-in)
• Single-shot work
• No clear completion signal (you'll loop forever)

Iron Rules

1. **Completion signal must be defined upfront** — "tests pass" or "build green" or "verifier APPROVES" 2. **Circuit breaker:** stop after 5 iterations OR after 3 identical failures 3. **State persisted between iterations** — what's been tried, what failed, why 4. **Never silently spin** — emit progress every iteration

Workflow

Iteration 1:
  - Run agent (e.g., @bolt-executor) with task
  - Check completion signal
  - If met: STOP, success
  - If not: record what was tried, what failed
  - Increment iteration counter

Iteration 2:
  - Run agent with task + accumulated state
  - Check completion signal
  - ...

Iteration 5 (max):
  - Stop and report: "Reached max iterations without completion"
  - Hand off to @apex-architect with full state dump

OR

3-identical-failure breaker:
  - If iteration N produces the same error fingerprint as N-1 and N-2
  - Stop immediately
  - The issue is no longer "fix the bug" — it's "question the approach"

Output

Per iteration, emit:

[ralph iteration {N}/{max}]
  Goal: {completion signal}
  Tried: {what this iteration did}
  Result: {success | failure: {reason}}
  State: {what's been tried so far}

Final report saved to `workspace/development/debug/[C]ralph-{topic}-{date}.md`.

Pairs With

• `@bolt-executor` (most common driver)
• `@hawk-debugger` (for bug-fix loops)
• `@oath-verifier` (provides the completion signal)
• `@apex-architect` (escalation when circuit breaker trips)

Cancellation

Interrupted by `dev-cancel` — preserves state for resume.