| name | ralph-wiggum |
| description | Executa loops autonomos de desenvolvimento via tecnica Ralph Wiggum.
Usar quando: (1) Iniciar loop Ralph na sessao atual, (2) Usuario diz "/ralph-loop",
(3) Explicar a tecnica Ralph Wiggum, (4) Configurar estrutura Ralph para um projeto,
(5) Usuario menciona "autonomous loop", "I'm in danger" ou "ralph".
|
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
- Create specs: Add requirement specs to
.claude/ralph-loop/specs/ directory
- Run planning:
./ralph-loop.sh plan 3 (3 iterations)
- Run building:
./ralph-loop.sh 10 (10 iterations)
Three Phases, Two Prompts, One Loop
| Phase | Prompt | Purpose |
|---|
| 1 | (human) | Define requirements, create specs |
| 2 | PROMPT_plan.md | Gap analysis: specs vs code → IMPLEMENTATION_PLAN.md |
| 3 | PROMPT_build.md | Implement, test, commit, push |
Loop Mechanics
Outer Loop (Bash)
while :; do cat PROMPT.md | claude ; done
Each iteration:
- Feeds prompt to Claude
- Agent completes ONE task
- Updates IMPLEMENTATION_PLAN.md
- Commits and exits
- Loop restarts with fresh context
Inner Loop Control
- Planning mode: Gap analysis only, no implementation
- Building mode: Implement, test, commit, push
Key Principles
- Context efficiency: One task per iteration
- Backpressure: Tests/lints reject invalid work
- Deterministic setup: Same files loaded each loop
- Self-correction: Plan is disposable, regenerate when wrong
Key Terminology
| Term | Definition |
|---|
| JTBD | Job-to-Be-Done - high-level user need |
| Topic of Concern | Distinct aspect within a JTBD |
| Spec | Requirements doc (.claude/ralph-loop/specs/FILENAME.md) |
| Task | Unit of work from specs vs code comparison |
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
