ralph-loop

# Ralph Wiggum Loop Mode

Named after the Simpsons character who "never stops despite being confused," this technique runs Claude Code in a loop where the prompt stays the same but the codebase accumulates changes. Each iteration reads previous work and continues until completion.

## When to Use Ralph Mode

**Ideal for:**
- Well-defined implementation tasks with clear completion criteria
- Refactoring or migration work (e.g., React v16 to v19)
- Test-driven development cycles (run until tests pass)
- Batch processing or repetitive tasks
- Overnight autonomous work sessions

**Not ideal for:**
- Tasks requiring design decisions or human judgment
- Exploratory work without clear end states
- Tasks where requirements may change mid-execution
- First-time implementations where you need to learn the code

## Activation Protocol

### Step 1: Validate Task Suitability

Before activating, confirm:
- [ ] Task has clear, measurable completion criteria
- [ ] Success can be verified programmatically (tests, build, specific file state)
- [ ] The work is in a git-tracked directory
- [ ] You understand what success looks like

### Step 2: Create State File

Create `.claude/ralph-loop.local.md` with the following structure:

```markdown
---
active: true
iteration: 0
max_iterations: 20
completion_promise: null
---

# Your Task Prompt Here

## Objective
[Clear statement of what needs to be accomplished]

## Completion Criteria
Complete when TODO.md shows [x] ALL_TASKS_COMPLETE

## Verification Commands
Run these to check progress:
- `[test command]`
- `[build command]`

## Context
- Read [relevant files] for specifications
- Follow [conventions file] for code style
```

### Step 3: Create TODO.md (Recommended Completion Method)

Create `TODO.md` in your project root:

```markdown
# Task Checklist

## Tasks
- [ ] Task 1
- [ ] Task 2
- [ ] Task 3

## Completion
- [ ] ALL_TASKS_COMPLETE
```

### Step 4: Start the Loop

Simply run Claude normally. The Stop hook will detect the state file and keep the loop running until completion is detected.

```bash
claude
```

## Two Completion Methods

### Method 1: TODO.md Markers (Recommended)

The hook checks `TODO.md` for `[x] ALL_TASKS_COMPLETE`. This is more reliable because:
- It's visible in the file system
- It can be tracked in git
- Claude can easily update it
- You can see progress (X/Y tasks complete)

### Method 2: Promise Tags (Legacy)

Set `completion_promise` in the state file and output `<promise>YOUR_TEXT</promise>` when complete.

```markdown
---
active: true
iteration: 0
max_iterations: 20
completion_promise: "feature implemented"
---
```

When Claude outputs `<promise>feature implemented</promise>`, the loop ends.

## Configuration Options

In `.claude/ralph-loop.local.md` frontmatter:

| Option | Default | Description |
|--------|---------|-------------|
| `active` | `true` | Set to `false` to disable loop |
| `iteration` | `0` | Current iteration count (auto-incremented) |
| `max_iterations` | `20` | Safety cap (0 = unlimited) |
| `completion_promise` | `null` | Text to match for promise completion |

## During Execution

### Iteration Status

Every iteration shows:
- Current iteration number
- Task progress (from TODO.md)
- Completion criteria
- Max iterations remaining

### Checkpoint Notifications

Every 5 iterations, you'll see a checkpoint reminder to:
- Review changes: `git log --oneline -10`
- Verify progress is on track
- Consider adjusting the prompt if stuck

### Manual Intervention

**To pause the loop:**
```bash
# Edit the state file
# Change active: true → active: false
```

**To stop immediately:**
```bash
rm .claude/ralph-loop.local.md
```

**To resume:**
```bash
# Re-create or edit the state file
# Set active: true
claude
```

## Safety Features

- **Iteration cap**: Prevents infinite loops (default: 20)
- **Git tracking**: Every change is revertible
- **Checkpoint notifications**: Reminders to review progress
- **Clear completion criteria**: Loop only exits on explicit success
- **Cost awareness**: Track iterations to estimate API costs

## Example: MetricFlow Phase 7-8

```markdown
---
active: true
iteration: 0
max_iterations: 25
completion_promise: null
---

# MetricFlow Phase 7-8: Educator Agent

## Objective
Implement the Educator Agent that uses Claude API to generate educational
explanations for code metrics.

## Completion Criteria
Complete when TODO.md shows [x] ALL_TASKS_COMPLETE

## Verification Commands
- `cd backend && python -m pytest tests/test_educator.py -v`
- `cd backend && python -c "from app.agents.educator import EducatorAgent; print('OK')"`

## Context
- Read docs/plans/MASTER_PLAN.md sections 5.3 (Educator Agent)
- Follow CLAUDE.md for project conventions
- Analyzer and Pattern agents already complete (use their output formats)

## Instructions
1. Check TODO.md for current task list
2. Implement next incomplete task
3. Write tests as you go
4. Run verification after each change
5. Mark [x] ALL_TASKS_COMPLETE when done
```

And corresponding `TODO.md`:

```markdown
# Phase 7-8: Educator Agent

## Tasks
- [ ] Create EducatorAgent class skeleton in backend/app/agents/educator.py
- [ ] Add Claude API client initialization
- [ ] Implement explain_complexity() method
- [ ] Implement explain_maintainability() method
- [ ] Implement explain_code_smells() method
- [ ] Add course concept mapping
- [ ] Write unit tests for all methods
- [ ] Integration test with Analyzer output

## Completion
- [ ] ALL_TASKS_COMPLETE
```

## Troubleshooting

**Loop won't start:**
- Check `.claude/ralph-loop.local.md` exists
- Verify `active: true` is set in frontmatter

**Loop won't stop:**
- Ensure TODO.md contains exactly `[x] ALL_TASKS_COMPLETE` (case-insensitive)
- Or check `completion_promise` matches your output tag
- Check `max_iterations` isn't set to 0 (unlimited)
- Manual stop: `rm .claude/ralph-loop.local.md`

**Stuck on same error:**
- Review the error pattern
- Adjust the prompt with more specific guidance
- Consider break