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.