---
name: ralph-loop
short_name: ralph
description: Ralph Loop - Interactive self-referential development for iterative task refinement
category: development
priority: P0
tags: [ralph, iterative, self-referential, loop, refinement]
---

# Ralph Loop Skill

**Ralph Loop** is a development technique for iterative, self-referential AI development. Based on Ralph Wiggum coding technique (persistent iteration despite setbacks), it enables continuous refinement until task completion.

## Core Philosophy

> **"Ralph is a Bash loop"** — Geoffrey Huntley

Ralph Loop creates a **self-referential feedback cycle** where:
- The prompt remains constant across iterations
- Previous work persists in files
- Each iteration sees modified files and history
- AI autonomously improves by reading its own past work

## When to Use Ralph Loop

**Good for:**
- ✅ Well-defined tasks with clear success criteria
- ✅ Tasks requiring iteration and refinement (e.g., getting tests to pass)
- ✅ Complex implementations that benefit from incremental approach
- ✅ Debugging where multiple attempts are expected
- ✅ Refactoring with many small improvements

**Not good for:**
- ❌ Tasks requiring human judgment or design decisions
- ❌ One-shot operations (simple file edits)
- ❌ Tasks with unclear success criteria
- ❌ Production debugging (use targeted debugging skill instead)

## Ralph Loop Process

### Phase 1: Setup

1. **Define Task Clearly**
   - What are you building?
   - What are the success criteria?
   - What should the output look like?

2. **Set Completion Promise**
   - Exact phrase that signals completion
   - Example: `<promise>TASK COMPLETE</promise>`
   - ONLY output when statement is completely and unequivocally TRUE

3. **Set Safety Limit**
   - Maximum iterations (recommended: 10-50)
   - Prevents infinite loops on impossible tasks

### Phase 2: Iteration Cycle

For each iteration:

```
1. Review previous work (files, git history, task context)
2. Identify next improvement or bug to fix
3. Make targeted changes (don't over-reach)
4. Verify changes work (run tests, read files)
5. Document what was done
6. Check if completion criteria met
```

### Phase 3: Completion

**ONLY output completion promise when ALL of:**
- ✅ Every requirement is met
- ✅ Tests pass (if applicable)
- ✅ Code is clean (no obvious bugs)
- ✅ Documentation is updated (if required)

**DO NOT output completion promise for:**
- ❌ Feeling stuck
- ❌ Running too long
- ❌ Thinking task is impossible
- ❌ Wanting to move on to something else

## Task State Management

Ralph Loop maintains state in `RALPH_STATE.md`:

```markdown
---
active: true
iteration: 3
max_iterations: 20
completion_promise: "TASK COMPLETE"
started_at: 2026-03-20T14:00:00Z
---

[Task description]
```

## Iteration Tracking

Each iteration increments the counter:

| Iteration | Focus | Changes | Status |
|-----------|--------|---------|---------|
| 1 | Initial implementation | Core files created | In progress |
| 2 | Bug fixes | Fixed issues found | In progress |
| 3 | Refinement | Improved code quality | ... |

## Best Practices

### 1. Clear Completion Criteria

❌ **Bad:** "Build a todo API and make it good."

✅ **Good:**
```markdown
Build a REST API for todos.

When complete:
- All CRUD endpoints working
- Input validation in place
- Tests passing (coverage > 80%)
- README with API docs
- Output: <promise>TASK COMPLETE</promise>
```

### 2. Incremental Goals

❌ **Bad:** "Create a complete e-commerce platform."

✅ **Good:**
```markdown
Phase 1: User authentication (JWT, tests)
Phase 2: Product catalog (list/search, tests)
Phase 3: Shopping cart (add/remove, tests)

Output <promise>TASK COMPLETE</promise> when all phases done.
```

### 3. Self-Correction First

❌ **Bad:** "Write code for feature X."

✅ **Good:**
```markdown
Implement feature X following TDD:
1. Write failing tests
2. Implement feature
3. Run tests
4. If any fail, debug and fix
5. Refactor if needed
6. Repeat until all green
7. Output: <promise>TASK COMPLETE</promise>
```

### 4. Safety Nets

Always set `max_iterations` as safety:

❌ **Risky:** "Ralph loop forever" (can get stuck)

✅ **Safe:**
```markdown
Max iterations: 20

If not complete by iteration 20:
- Document what's blocking progress
- List what was attempted
- Suggest alternative approaches
```

## Ralph Loop Commands

### Starting a Ralph Loop

```
Task: Start Ralph Loop with task description

Parameters:
- task: Clear description of what to build/fix
- max_iterations: Safety limit (default: 50)
- completion_promise: Exit phrase (required)

Example:
"Start Ralph Loop: Build a REST API for todos with CRUD operations, input validation, and tests. Max iterations: 20. Completion promise: <promise>TASK COMPLETE</promise>"
```

### Continuing an Iteration

When returning to continue iteration:

```
Task: Continue Ralph Loop iteration N

I will:
1. Review previous work in files
2. Identify next improvement
3. Make targeted changes
4. Verify and document
5. Check completion criteria
```

### Checking Status

```
Task: Check Ralph Loop status

Check:
- Current iteration number
- Max iterations remaining
- Completion promise status
- Recent changes made
```

## Anti-Patterns

What Ralph Loop **refuses**:

1. **False Completion Promises**
   - Never output completion promise when not genuinely complete
   - Even if stuck, frustrated, or want to move on
   - The loop is designed to continue until genuine completion

2. **Large, Vague Iterations**
   - Each iteration should be focused and small
   - Don't try to do everything in one iteration
   - Incremental > ambitious but incomplete

3. **Ignoring Previous Work**
   - Always review files modified in previous iterations
   - Build on top of existing work
   - Don't start fresh each time

4. **Skipping Verification**
   - Read back files after changes
   - Run tests after implementation
   - Verify changes work before claiming done

5. **Abandoning Too Early**
   - 3 attempts is the minimum for any approach
   - If approach keeps failing, pivot strategy
   - Don't give up after one or two tries

## Integration with Gold Standard

Ralph Loop enforces Gold Standard principles:

| Gold Standard Rule | Ralph Loop Application |
|-------------------|----------------------|
| Read-Back Verification | Review files before each iteration |
| Executable Proof | Run tests/show output after changes |
| Loop Prevention | Max iterations is the ultimate limit |
| Evidence Over Claims | Show test results, file contents |

## When to Stop Ralph Loop

**Stop when:**
- ✅ All completion criteria met
- ✅ Max iterations reached (document blockers)
- ✅ User explicitly cancels

**Don't stop when:**
- ❌ Feeling stuck (iterate differently instead)
- ❌ Taking longer than expected (that's Ralph's point)
- ❌ Wanting to try a different task (finish current one first)

## Example Ralph Loop Session

**Initial Task:**
```
"Build a REST API for todos with CRUD operations, input validation, and tests.
Max iterations: 20. Completion promise: <promise>TASK COMPLETE</promise>"
```

**Iteration 1:**
- Create Express server
- Add basic todo model
- Implement GET /todos endpoint
- Tests failing (no validation yet)
- Status: Incomplete

**Iteration 2:**
- Add POST /todos endpoint
- Add input validation middleware
- Add DELETE /todos endpoint
- Tests partially passing
- Status: Incomplete

**Iteration 3:**
- Fix validation bugs
- Add PUT /todos endpoint
- All endpoints working
- Tests passing but coverage low
- Status: Incomplete

**Iteration 10:**
- Add comprehensive test suite
- Achieve >80% coverage
- Add README with API documentation
- All requirements met
- Status: **<promise>TASK COMPLETE</promise>**

---

## Philosophy Summary

Ralph Loop embodies:
1. **Iteration > Perfection** - Let the loop refine work over time
2. **Failures Are Data** - Use failures to tune approach
3. **Persistence Wins** - Keep trying until success
4. **Self-Referential** - Learn from previous iterations

**"The Ralph Loop doesn't care if you're good or fast. It only cares that you keep trying until you win."**