🤖 Ralph Wiggum Workflow

A comprehensive guide to autonomous AI development using the Ralph Wiggum technique.

📑 Table of Contents

What is Ralph Wiggum?
How to Set Up
The Workflow
Phase 1: Clarify
Phase 2: Plan
Phase 3: Execute
Templates
Commands Reference
When to Use What
Troubleshooting
Advanced Patterns
Cost Awareness
Real-World Results
Philosophy Recap
Sources

🧠 What is Ralph Wiggum?

Ralph Wiggum is an autonomous development technique created by Geoffrey Huntley. At its core, it's simple:

while :; do cat PROMPT.md | claude ; done

A bash loop that repeatedly feeds the same prompt to an AI agent until the task is complete.

Philosophy

"The technique is deterministically bad in an undeterministic world."

When Ralph fails, you don't blame the tools — you tune the prompts
Failures are predictable and informative
Success requires faith in eventual consistency
Each failure teaches you what "signs" (guardrails) to add

The Playground Metaphor

From Huntley:

"Ralph is very good at making playgrounds, but he comes home bruised because he fell off the slide, so one then tunes Ralph by adding a sign next to the slide saying 'SLIDE DOWN, DON'T JUMP, LOOK AROUND,' and Ralph is more likely to look and see the sign."

Eventually, the prompt has enough guardrails that Ralph works reliably.

🔧 How to Set Up

Prerequisites

Requirement	Description
Claude Code	Already installed and authenticated
Git	For state tracking and memory

Step 1: Install the Ralph Wiggum Plugin

From within a Claude Code session:

/install-github-plugin anthropics/claude-code plugins/ralph-wiggum

Verify it's installed:

/plugins

You should see ralph-wiggum listed.

Step 2: Set Up a New Project

# Create project directory
mkdir my-project
cd my-project

# Initialize git (required for Ralph's memory)
git init

# Create the Ralph files
mkdir -p .claude
touch PROMPT.md TODO.md .claude/clarify-session.md

# Optional: Create CLAUDE.md for project memory
touch CLAUDE.md

Step 3: Verify Setup

Start Claude Code in your project:

claude

Test the Ralph plugin:

/ralph-loop "Say hello and output DONE" --max-iterations 1 --completion-promise "DONE"

If it runs and completes, you're ready.

Project Structure After Setup

my-project/
├── .git/                      # Git repo (required)
├── .claude/
│   ├── commands/
│   │   ├── ralph-clarify.md   # Phase 1: Requirements discovery
│   │   └── ralph-plan.md      # Phase 2: Generate execution files
│   └── clarify-session.md     # Requirements (from interview)
├── PROMPT.md                  # Ralph's instructions (generated by /ralph-plan)
├── TODO.md                    # Task checklist (generated by /ralph-plan)
├── CLAUDE.md                  # Project memory (optional)
└── src/                       # Your code (created during execution)

Step 4: Install the Clarify Command

The /ralph-clarify command runs the 40-70 question interview phase. You need to create the command file.

📄 Click to expand full ralph-clarify.md file

Create the commands directory:

mkdir -p .claude/commands

Create .claude/commands/ralph-clarify.md with this content:

---
description: Comprehensive requirements discovery via iterative questioning
argument-hint: "topic to clarify" [--max-iterations N]
---

# Ralph Clarify: Iterative Discovery Loop

Use the Ralph loop to exhaustively gather requirements through structured questioning. The loop pressure overrides the natural tendency to stop asking after 3-5 questions.

## Parse Arguments

Arguments: $ARGUMENTS

Split arguments:
- **TOPIC**: Everything before `--` flags (what we're clarifying)
- **--max-iterations**: Number (default: 30)

## Setup

1. Create discovery file at `.claude/clarify-session.md`:

# Discovery: {TOPIC}

Started: {timestamp}

## Questions Asked

(Track all questions to avoid repetition)

## Answers Received

(Capture user responses)

## Emerging Requirements

(Synthesize as patterns emerge)

2. Start Ralph loop with discovery prompt:

/ralph-loop "{DISCOVERY_PROMPT}" --max-iterations {N} --completion-promise "CLARIFIED"

## Discovery Prompt

Build this prompt for the ralph-loop:

You are conducting comprehensive requirements discovery for: {TOPIC}

## Your Task

Use the AskUserQuestion tool to ask clarifying questions. Keep asking until you have exhaustively covered all aspects needed to create a complete plan.

## Each Iteration

1. Read `.claude/clarify-session.md` for questions already asked
2. Identify gaps in understanding
3. Ask 2-4 NEW questions via AskUserQuestion (never repeat)
4. After user answers, update `.claude/clarify-session.md`:
   - Add questions to "Questions Asked"
   - Add answers to "Answers Received"
   - Update "Emerging Requirements" with new insights
5. Continue to next iteration

## Question Categories to Cover

Work through these systematically (not all at once):

**Core Requirements**
- What must this do? What's the minimum viable version?
- What's explicitly out of scope?

**Users & Context**
- Who uses this? What's their skill level?
- What environment/constraints exist?

**Integration Points**
- What existing systems does this touch?
- What data flows in/out?

**Edge Cases**
- What happens when things go wrong?
- What are the boundary conditions?

**Quality Attributes**
- Performance requirements?
- Security considerations?

**Existing Patterns**
- How do similar things work in this codebase?
- What conventions should we follow?

**Preferences**
- Any strong opinions on approach?
- Tradeoffs: simplicity vs flexibility vs performance?

## Question Design

Use AskUserQuestion effectively:
- 2-4 options per question (not too many)
- Include "Other" implicitly (tool provides it)
- Group related questions in one call (max 4 questions per call)
- Make options concrete, not vague

## Completion Criteria

Output <promise>CLARIFIED</promise> ONLY when:
- You've covered all question categories above
- You've asked follow-up questions on complex answers
- You genuinely cannot think of more meaningful questions
- The discovery file has comprehensive requirements

Typical sessions: 40-70 questions across 15-25 iterations.

## If User Says "Enough"

If the user indicates they want to stop (selects "enough", "stop", "let's move on"):
- Summarize what you've learned in the discovery file
- Note any gaps that remain
- Output <promise>CLARIFIED</promise>

## Output Location

All discoveries saved to: `.claude/clarify-session.md`

## Confirmation

After setup, output:

Starting comprehensive discovery for: {TOPIC}

This will use iterative questioning to gather requirements exhaustively.
Expect 40-70 questions across multiple categories.

Discovery file: .claude/clarify-session.md

To stop early, answer any question with "enough" or "let's move on".

Beginning discovery...

Then immediately start the ralph-loop with the discovery prompt.

Now you can run:

/ralph-clarify "Build a REST API"

Note: The AskUserQuestion tool is built into Claude Code — no extra install needed.

Step 5: Install the Plan Command

The /ralph-plan command converts your clarify session into execution files. Create the command file:

Create .claude/commands/ralph-plan.md with the content shown in Phase 2: Plan
Now you can run:

/ralph-plan --vertical-slice

This generates PROMPT.md and TODO.md from your requirements.

⚡ Quick Start (TL;DR)

# Per-project setup
mkdir my-project && cd my-project
git init
mkdir -p .claude/commands
touch PROMPT.md TODO.md .claude/clarify-session.md

Then inside Claude Code:

# Install Ralph plugin (one-time)
/install-github-plugin anthropics/claude-code plugins/ralph-wiggum

# Phase 1: Clarify - gather requirements (40-70 questions)
/ralph-clarify "Build a REST API"

# Phase 2: Plan - convert requirements to execution files
/ralph-plan --vertical-slice

# Phase 3: Execute - run the autonomous loop
/ralph-loop "Read PROMPT.md and execute" --max-iterations 50 --completion-promise "DONE"

# Cancel if needed
/cancel-ralph

Ralph Loop Command Syntax

/ralph-loop "<prompt>" --max-iterations <n> --completion-promise "<text>"

Parameter	Required	Description
`<prompt>`	✅	The task description
`--max-iterations <n>`	⭐	Safety limit to prevent infinite loops
`--completion-promise "<text>"`	⭐	Exact string that signals task is done

Example:

/ralph-loop "Build a REST API for todos. Output DONE when complete." --max-iterations 50 --completion-promise "DONE"

🔄 The Workflow

┌──────────────────────────────────────────────────────────────────────────┐
│                           PHASE 1: CLARIFY                               │
│                                                                          │
│   Command: /ralph-clarify "Your project idea"                            │
│                                                                          │
│   📋 40-70 questions via AskUserQuestion                                 │
│   → Exhaustive requirements discovery                                    │
│   → Output: .claude/clarify-session.md                                   │
└──────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌──────────────────────────────────────────────────────────────────────────┐
│                            PHASE 2: PLAN                                 │
│                                                                          │
│   Command: /ralph-plan [--vertical-slice]                                │
│                                                                          │
│   📝 Convert requirements to actionable tasks                            │
│   → Create PROMPT.md (execution instructions + guardrails)               │
│   → Create TODO.md (prioritized task checklist)                          │
└──────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│                          PHASE 3: EXECUTE                                    │
│                                                                              │
│   Command: /ralph-loop "Read PROMPT.md and execute" \                        │
│            --max-iterations 50 --completion-promise "DONE"                   │
│                                                                              │
│   🔁 Ralph loop until complete                                               │
│   → Pick task → Complete → Mark done → Repeat                                │
│   → Output: Working software                                                 │
└──────────────────────────────────────────────────────────────────────────────┘

📋 Phase 1: Clarify

The clarify phase uses the Ralph loop + AskUserQuestion to overcome the model's natural tendency to stop asking after 3-5 questions. By forcing iteration, you get 40-70 questions covering all aspects of the project.

Why This Matters

"The loop pressure overrides the natural tendency to stop asking after 3-5 questions."

Models aren't trained to work autonomously for long periods. Ralph forces them to keep going.

Question Categories

Work through these systematically:

Category	Questions to Cover
Core Requirements	What must this do? What's MVP? What's out of scope?
Users & Context	Who uses this? What's their skill level? What constraints exist?
Technical Choices	Language? Framework? Database? Dependencies?
Integration Points	What systems does this connect to? What data flows in/out?
Edge Cases	What happens when things fail? Boundary conditions?
Quality Attributes	Performance requirements? Security considerations?
Existing Patterns	How do similar things work in this codebase? Conventions?
Preferences	Strong opinions on approach? Tradeoffs?

Running the Clarify Phase

Option 1: Manual (Recommended for Learning)

Start Claude and prompt:

I want to build [YOUR PROJECT IDEA].

Before we write any code, interview me thoroughly to understand the requirements.
Ask 40-70 questions covering:
- Core functionality and features
- Technical constraints (language, framework, dependencies)
- Architecture preferences
- Edge cases and error handling
- Testing requirements
- Success criteria

Use AskUserQuestion to gather my answers efficiently. Group related questions.
After the interview, compile everything into .claude/clarify-session.md

Option 2: Using /ralph-clarify Skill

If you have the skill installed:

/ralph-clarify "Build a REST API for task management"

This will:

Create .claude/clarify-session.md
Run Ralph loop with AskUserQuestion
Ask 40-70 questions across 15-25 iterations
Compile requirements into the session file

Output: `clarify-session.md`

# Discovery: [Project Name]

Started: [timestamp]

## Questions Asked
1. What authentication method? → JWT
2. What database? → PostgreSQL
3. ...

## Answers Received
- Authentication: JWT with refresh tokens
- Database: PostgreSQL with Prisma ORM
- ...

## Emerging Requirements
- Must support 1000 concurrent users
- API must be RESTful with OpenAPI spec
- All endpoints require authentication except /health
- ...

📝 Phase 2: Plan

Convert the clarify session into actionable instructions.

Using /ralph-plan (Recommended)

The /ralph-plan command automatically generates PROMPT.md and TODO.md from your clarify session:

# Basic usage
/ralph-plan

# With vertical slice development (recommended for MVPs)
/ralph-plan --vertical-slice

# Limit initial tasks
/ralph-plan --max-tasks 20

This reads .claude/clarify-session.md and generates:

PROMPT.md — Execution instructions with guardrails
TODO.md — Prioritized task checklist with HARD STOP checkpoints

📄 Click to expand full ralph-plan.md command file

Create .claude/commands/ralph-plan.md with this content:

---
description: Convert clarify-session.md into PROMPT.md and TODO.md for Ralph execution (project)
argument-hint: [--vertical-slice] [--max-tasks N]
---

# Ralph Plan: Requirements to Execution Files

Convert discovered requirements into actionable execution files for the Ralph loop.

## Parse Arguments

Arguments: $ARGUMENTS

- **--vertical-slice**: If present, structure TODO for vertical slice development (end-to-end for simplest case first)
- **--max-tasks N**: Limit initial TODO to N tasks (default: unlimited)

## Your Task

Read `.claude/clarify-session.md` and generate two files:

### 1. Generate `PROMPT.md`

Create a focused, actionable prompt file (~100-200 words is ideal). Structure:

# PROMPT.md

## Project
[One-line project description from clarify-session.md]

## Requirements
Full requirements in `.claude/clarify-session.md`

## Each Iteration

1. Read `TODO.md` for current tasks
2. Pick the highest priority incomplete task (top `- [ ]` item)
3. Read any files before editing them
4. Implement the task completely
5. Run tests/validation relevant to the task
6. If tests fail, fix before continuing
7. Mark task complete in `TODO.md` with `[x]`
8. Commit changes: `git add -A && git commit -m "descriptive message"`
9. Continue to next task

## Guardrails

- Always read files before editing
- Never skip failing tests
- If tests fail 3 times on same issue, output: <promise>STUCK</promise>
- Don't refactor unrelated code
- Keep changes focused on current task
- Update TODO.md immediately after completing each task

## Completion

When all tasks in TODO.md are marked `[x]` and tests pass, output:

<promise>DONE</promise>

Customize the Project section and add any project-specific guardrails based on the requirements.

### 2. Generate `TODO.md`

Create a prioritized task checklist. Structure:

# TODO

## Critical (MVP - Must Complete)
- [ ] Task 1: Clear, specific, measurable outcome
- [ ] Task 2: Another specific task
- [ ] **HARD STOP** - Verify core flow works end-to-end

## High Priority
- [ ] Task with specific outcome
- [ ] Another task

## Medium Priority
- [ ] Task description
- [ ] **HARD STOP** - Review before continuing to low priority

## Low Priority / Nice-to-Have
- [ ] Optional enhancement

---
## Completed
(Tasks move here when done)

### Task Writing Rules

1. **Be Specific**: "Add JWT auth middleware to /api routes" not "Add authentication"
2. **Be Measurable**: Include success criteria when possible
3. **One Thing Per Task**: Split compound tasks
4. **Include Context**: Reference specific files/functions when known
5. **Order by Dependency**: Tasks that enable others come first

### Vertical Slice Pattern (if --vertical-slice)

If vertical slice flag is set, reorganize Critical section to deliver one complete end-to-end flow first:

## Critical (Vertical Slice - Simplest Complete Flow)
- [ ] Set up project structure (package.json, tsconfig, etc.)
- [ ] Implement simplest happy path end-to-end
- [ ] Add basic test for the happy path
- [ ] **HARD STOP** - Verify slice works before expanding

### HARD STOP Placement

Insert `**HARD STOP**` markers at:
- After core infrastructure is set up
- After MVP/vertical slice is complete
- Before moving to lower priority items
- At any point requiring human judgment

## Output

After generating both files, output:

Created execution files from requirements:

PROMPT.md - Execution instructions for Ralph loop
TODO.md   - [N] tasks across [M] priority levels

To start execution:
/ralph-loop "Read PROMPT.md and execute" --max-iterations 50 --completion-promise "DONE"

Review the files before starting. Add guardrails to PROMPT.md if you notice patterns Ralph might get wrong.

Manual Alternative

If you prefer to create these files manually:

Simple PROMPT.md (~100 words — what actually works best)

# PROMPT.md

Your job is to build [PROJECT] based on the requirements in .claude/clarify-session.md

Track progress in TODO.md. After completing each task:
1. Mark it done in TODO.md
2. Commit your changes
3. Move to the next task

When all tasks are complete and tests pass, output: DONE

Structured PROMPT.md (with guardrails)

# PROMPT.md

## Project
Build [PROJECT DESCRIPTION]

## Requirements
Read .claude/clarify-session.md for full requirements.

## Instructions
1. Read TODO.md to see current tasks
2. Pick the highest priority incomplete task
3. Before editing any file, read it first
4. Implement the task
5. Run tests to verify
6. Mark task complete in TODO.md
7. Commit changes with descriptive message
8. Continue to next task

## Guardrails
- Never skip tests
- If tests fail, fix before moving on
- Don't refactor unrelated code
- Keep changes focused on current task

## Success Criteria
- All tasks in TODO.md marked complete
- All tests passing
- No linter errors

## When Done
Output: DONE

TODO.md Template

# TODO

## Critical (MVP - Must Complete)
- [ ] Set up project structure
- [ ] Configure database connection
- [ ] Implement core feature end-to-end
- [ ] **HARD STOP** - Verify core flow works

## High Priority
- [ ] Implement user authentication
- [ ] Create CRUD endpoints

## Medium Priority
- [ ] Add input validation
- [ ] Implement error handling
- [ ] Write unit tests
- [ ] **HARD STOP** - Review before nice-to-haves

## Low Priority / Nice-to-Have
- [ ] Add API documentation
- [ ] Create example requests
- [ ] Write README

---
## Completed
(Tasks move here when done)

Project Structure

your-project/
├── .claude/
│   ├── commands/
│   │   ├── ralph-clarify.md   # Phase 1 command
│   │   └── ralph-plan.md      # Phase 2 command
│   └── clarify-session.md     # Requirements from interview
├── PROMPT.md                   # Ralph's instructions (generated)
├── TODO.md                     # Task checklist (generated)
├── CLAUDE.md                   # Project memory (optional)
└── src/                        # Your code

🚀 Phase 3: Execute

Run the Ralph loop until complete.

Using the Ralph Plugin (Recommended)

/ralph-loop "Read PROMPT.md and execute the tasks" --max-iterations 50 --completion-promise "DONE"

Parameters:

--max-iterations N — Safety limit (always set this!)
--completion-promise "TEXT" — String that signals completion

Using Bash Loop (Original Method)

while :; do cat PROMPT.md | claude -p --dangerously-skip-permissions; done

Flags:

-p — Print mode (non-interactive)
--dangerously-skip-permissions — Skip confirmation prompts (use with caution)

What Happens During Execution

Iteration 1: Claude reads PROMPT.md → Picks Task 1 → Implements → Commits
     ↓
Iteration 2: Claude reads PROMPT.md → Sees Task 1 done → Picks Task 2 → Implements → Commits
     ↓
Iteration 3: ...
     ↓
Iteration N: All tasks done → Claude outputs "DONE" → Loop exits

Each iteration:

Sees the same PROMPT.md
But files have changed (previous work persists)
Git history shows progress
TODO.md reflects completed tasks

📄 Templates

Minimal PROMPT.md (Start Here)

# PROMPT.md

Build [WHAT YOU'RE BUILDING].

Requirements:
- [Requirement 1]
- [Requirement 2]
- [Requirement 3]

Track progress in TODO.md. Commit after each completed item.

When all requirements are implemented and tests pass, output: DONE

PROMPT.md with Guardrails

# PROMPT.md

## Task
[Description of what to build]

## Requirements
[From clarify-session.md or listed here]

## Instructions
1. Read TODO.md for current tasks
2. Pick highest priority incomplete task
3. Read any files before editing them
4. Implement the task
5. Run tests
6. If tests fail, fix before continuing
7. Mark complete in TODO.md
8. Commit with clear message
9. Repeat until all tasks done

## Signs (Guardrails)
- Always read before editing
- Never skip failing tests
- Don't refactor unrelated code
- Keep commits focused
- Update TODO.md immediately after completing tasks

## Completion
When TODO.md shows all tasks complete and tests pass, output: DONE

TODO.md Template

# TODO

## Critical (Must Have)
- [ ] Task 1
- [ ] Task 2

## Important (Should Have)
- [ ] Task 3
- [ ] Task 4

## Nice to Have
- [ ] Task 5
- [ ] Task 6

---
## Completed
- [x] Example completed task

CLAUDE.md (Project Memory)

# Project: [Name]

## Tech Stack
- Language: [e.g., TypeScript]
- Framework: [e.g., Express]
- Database: [e.g., PostgreSQL]

## Conventions
- [Convention 1]
- [Convention 2]

## Commands
- `npm run dev` — Start dev server
- `npm test` — Run tests
- `npm run build` — Build for production

## Learnings
- [Lesson learned during development]
- [Another lesson]

📚 Commands Reference

Starting a New Project

# 1. Create project directory
mkdir my-project && cd my-project
git init

# 2. Create the required files/directories
mkdir -p .claude/commands
touch .claude/clarify-session.md

# 3. Copy command files into .claude/commands/
#    - ralph-clarify.md (See Step 4 in "How to Set Up")
#    - ralph-plan.md (See Step 5 in "How to Set Up")
#
# Or copy from an existing project that has these files

Ralph Plugin Commands

# Start a Ralph loop
/ralph-loop "<prompt>" --max-iterations <n> --completion-promise "<text>"

# Cancel an active loop
/cancel-ralph

Custom Workflow Commands

# Phase 1: Clarify - gather requirements (requires command file)
/ralph-clarify "Your project description"
/ralph-clarify "Build a REST API" --max-iterations 25

# Phase 2: Plan - convert requirements to execution files (requires command file)
/ralph-plan
/ralph-plan --vertical-slice
/ralph-plan --vertical-slice --max-tasks 20

Complete Workflow Examples

# Full workflow: Clarify → Plan → Execute
/ralph-clarify "Build a habit tracking CLI"
# ... answer 40-70 questions ...
/ralph-plan --vertical-slice
# ... review generated PROMPT.md and TODO.md ...
/ralph-loop "Read PROMPT.md and execute" --max-iterations 50 --completion-promise "DONE"

# Skip clarify (when requirements are already clear)
/ralph-plan  # manually edit clarify-session.md first, or...
/ralph-loop "Build X with Y. Output DONE when complete." --max-iterations 30 --completion-promise "DONE"

Alternative: Bash Loop (Original Method)

# Basic loop
while :; do cat PROMPT.md | claude -p; done

# Skip permissions (use with caution)
while :; do cat PROMPT.md | claude -p --dangerously-skip-permissions; done

Monitoring Progress

# Watch git commits
watch -n 5 'git log --oneline -10'

# Watch TODO.md
watch -n 5 'cat TODO.md'

# Watch for file changes
watch -n 5 'ls -la src/'

🎯 When to Use What

Situation	Approach
Clear requirements, well-defined scope	Skip clarify → `/ralph-plan` or manual PROMPT.md → Ralph loop
Ambiguous requirements, greenfield	`/ralph-clarify` → `/ralph-plan --vertical-slice` → Ralph loop
Porting/migration (X to Y)	Simple `PROMPT.md` (~50 words) → Ralph loop
Complex feature, many decisions	`/ralph-clarify` → `/ralph-plan` with guardrails → Ralph loop
MVP / new project	`/ralph-clarify` → `/ralph-plan --vertical-slice` → Ralph loop
Ralph keeps failing	Add more "signs" (guardrails) to `PROMPT.md`
Ralph goes in circles	Check `TODO.md` is being updated; add explicit state tracking

🔧 Troubleshooting

Ralph Keeps Making the Same Mistake

Add a guardrail:

## Signs
- DO NOT [thing Ralph keeps doing wrong]
- ALWAYS [correct behavior]

Ralph Doesn't Update `TODO.md`

Make it explicit:

## After EVERY Task
1. Mark the task complete in TODO.md with [x]
2. Commit: `git add TODO.md && git commit -m "Mark [task] complete"`
3. Then continue to next task

Ralph Runs Forever

Always set --max-iterations:

/ralph-loop "..." --max-iterations 30 --completion-promise "DONE"

Tests Keep Failing

Add a hard stop:

## Guardrails
- If tests fail 3 times on the same issue, STOP and output: STUCK
- Do not proceed with broken tests

Context Getting Too Large

Ralph handles this via git + file state. But you can help:

## State Management
- All progress tracked in TODO.md
- Don't rely on conversation memory
- Read TODO.md at start of each iteration

🚀 Advanced Patterns

Template Variants

Different tasks benefit from different iteration patterns:

Template	Use When	Completion Promise
Feature	Building new functionality	`DONE`
TDD	Test-first development	`TESTS_PASS`
Bug Fix	Reproducing and fixing issues	`FIXED`
Refactor	Restructuring without behavior change	`REFACTORED`

TDD Template

## Each Iteration (TDD)
1. Write failing test for next requirement
2. Run test, confirm it fails
3. Implement minimum code to pass
4. Run tests, confirm green
5. Refactor if needed (tests must stay green)
6. Mark task complete, commit
7. Repeat until all requirements covered

## Success Criteria
- All tests passing
- Test coverage >80% for new code
- No skipped tests

## When Done
Output: <promise>TESTS_PASS</promise>

Bug Fix Template

## Each Iteration (Bug Fix)
1. Reproduce the bug with a failing test
2. Identify root cause
3. Implement fix
4. Run tests, confirm bug is fixed
5. Add regression test if not already covered
6. Verify no new issues introduced
7. Document the fix in commit message

## Guardrails
- If unable to reproduce after 5 attempts, output: <promise>CANNOT_REPRODUCE</promise>
- If fix causes other tests to fail, revert and try different approach

## When Done
Output: <promise>FIXED</promise>

Refactor Template

## Each Iteration (Refactor)
1. Run all tests, confirm green baseline
2. Make one refactoring change
3. Run tests immediately
4. If tests fail, revert and try smaller change
5. Commit when green
6. Repeat until refactoring complete

## Guardrails
- NEVER change behavior, only structure
- All existing tests must pass at all times
- Make small, incremental changes
- If tests fail 3 times, output: <promise>STUCK</promise>

## When Done
Output: <promise>REFACTORED</promise>

Parallel Development with Git Worktrees

Run multiple Ralph loops simultaneously on different features:

# Create isolated worktrees for parallel development
git worktree add ../project-auth feature/auth
git worktree add ../project-api feature/api

# Terminal 1: Work on auth
cd ../project-auth
claude
/ralph-loop "Implement authentication" --max-iterations 30 --completion-promise "DONE"

# Terminal 2: Work on API (simultaneously)
cd ../project-api
claude
/ralph-loop "Build API endpoints" --max-iterations 30 --completion-promise "DONE"

# When done, merge both features
git worktree remove ../project-auth
git worktree remove ../project-api

Overnight Batch Automation

Queue multiple phases to run while you sleep:

#!/bin/bash
# overnight-ralph.sh

echo "Starting overnight Ralph run at $(date)"

# Phase 1: Core implementation
claude -p "Read PROMPT.md and complete Phase 1 tasks. Output PHASE1_DONE when complete." \
  --max-iterations 30

# Phase 2: API layer
claude -p "Read PROMPT.md and complete Phase 2 tasks. Output PHASE2_DONE when complete." \
  --max-iterations 40

# Phase 3: Tests
claude -p "Read PROMPT.md and complete Phase 3 tasks. Output PHASE3_DONE when complete." \
  --max-iterations 20

echo "Completed at $(date)"
git log --oneline -20

Run it:

chmod +x overnight-ralph.sh
nohup ./overnight-ralph.sh > ralph.log 2>&1 &

Multi-Phase Sequencing

For complex projects, structure TODO.md with explicit phases:

# TODO

## Phase 1: Foundation
- [ ] Set up project structure
- [ ] Configure database
- [ ] Create base models
- [ ] **PHASE_1_COMPLETE** - Verify foundation works

## Phase 2: Core Features
- [ ] Implement main workflow
- [ ] Add validation
- [ ] **PHASE_2_COMPLETE** - Verify features work

## Phase 3: Polish
- [ ] Add error handling
- [ ] Write tests
- [ ] Documentation
- [ ] **PHASE_3_COMPLETE** - Ready for review

Run each phase with its own loop:

/ralph-loop "Complete Phase 1 tasks in TODO.md" --max-iterations 20 --completion-promise "PHASE_1_COMPLETE"
/ralph-loop "Complete Phase 2 tasks in TODO.md" --max-iterations 30 --completion-promise "PHASE_2_COMPLETE"
/ralph-loop "Complete Phase 3 tasks in TODO.md" --max-iterations 20 --completion-promise "PHASE_3_COMPLETE"

Prompt Tuning Methodology

When Ralph fails, don't blame the model — tune the prompt:

Start minimal — Begin with ~100 words
Observe failures — Note what Ralph gets wrong
Add signs — Each failure becomes a guardrail
Iterate — Run again, observe, refine
Stabilize — Eventually defects disappear

Example evolution:

# Version 1 (fails: doesn't run tests)
Build the feature. Output DONE when complete.

# Version 2 (fails: commits broken code)
Build the feature. Run tests after each change. Output DONE when complete.

# Version 3 (works!)
Build the feature.
After each change: run tests. If tests fail, fix before continuing.
Never commit with failing tests.
Output DONE when all tasks complete and tests pass.

💰 Cost Awareness

Scenario	Estimated Cost
50 iterations, medium codebase	$50-100
Overnight run (100+ iterations)	$100-200+
3-month language compiler (Cursed)	Unknown, but significant

Tips:

Set --max-iterations conservatively
Monitor usage during long runs
Use cheaper models for simple tasks if available

🏆 Real-World Results

Result	Description
$50k → $297	One engineer used Ralph for a full MVP
6 repos overnight	YC hackathon with parallel Ralph loops
Cursed compiler	3-month Ralph loop created a functional compiler with LLVM backend

💡 Philosophy Recap

Simple is better — 100 words beats 1,500 words
Iterate, don't perfect — Let the loop refine
Tune the prompts — When Ralph fails, add guardrails
Trust the process — Eventual consistency works
Track state in files — Git + TODO.md = memory

📖 Sources

Made with 🤖 and loops

"I'm in danger!" — Ralph Wiggum

]]>

Mburdo/Ralph_Wiggum_Loops.md