Ralph Wiggum Technique

The Ralph Wiggum technique is an AI development methodology using autonomous loops to reduce development effort. Named after the Simpsons character ("I'm in danger!").

Available Commands

/ralph-loop (or skill:ralph-wiggum:ralph-loop)

Start Ralph loop in current Claude Code session.

/help (or skill:ralph-wiggum:help)

Explain Ralph Wiggum technique and available commands.

/cancel-ralph (or skill:ralph-wiggum:cancel-ralph)

Cancel active Ralph loop.

Quick Start

1. Create specs: Add requirement specs to .claude/ralph-loop/specs/ directory
2. Run planning: ./ralph-loop.sh plan 3 (3 iterations)
3. Run building: ./ralph-loop.sh 10 (10 iterations)

Three Phases, Two Prompts, One Loop

Loop Mechanics

Outer Loop (Bash)

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

Each iteration:

1. Feeds prompt to Claude
2. Agent completes ONE task
3. Updates IMPLEMENTATION_PLAN.md
4. Commits and exits
5. Loop restarts with fresh context

Inner Loop Control

• Planning mode: Gap analysis only, no implementation
• Building mode: Implement, test, commit, push

Key Principles

1. Context efficiency: One task per iteration
2. Backpressure: Tests/lints reject invalid work
3. Deterministic setup: Same files loaded each loop
4. Self-correction: Plan is disposable, regenerate when wrong

Key Terminology

When to Regenerate Plan

• Ralph goes off track (implementing wrong things)
• Plan feels stale or doesn't match current state
• Too much clutter from completed items
• Significant spec changes made
• Confused about what's actually done

File Structure

project/.claude/ralph-loop/
├── ralph-loop.sh          # Loop script
├── PROMPT_build.md        # Build instructions
├── PROMPT_plan.md         # Plan instructions
├── AGENTS.md              # Operational guide
├── IMPLEMENTATION_PLAN.md # Task list (generated)
└── specs/                 # Requirements

Security Warning

Running with --dangerously-skip-permissions exposes:

• API keys
• SSH keys
• Browser cookies

Always use Docker (see docker-compose.ralph.yml):

docker-compose -f docker-compose.ralph.yml run ralph
./ralph-loop.sh plan 3

Language Patterns

Key phrases that signal proper Ralph behavior:

• "study" (not "read" or "look at")
• "don't assume not implemented"
• "using parallel subagents"
• "Ultrathink"
• "capture the why"
• "keep it up to date"

References

• See references/workflow.md for detailed workflow
• See scripts/init_ralph_project.py to initialize structure