name: ralph-wiggum description: Implements Geoffrey Huntley's Ralph Wiggum autonomous iteration technique for managing LLM context. Use when working on long-running tasks, when context is getting polluted, or when you need autonomous development with deliberate context rotation. Treats LLM context like memory - rotates to fresh context before pollution builds up, with state persisting in files and git.

Ralph Wiggum Method

An autonomous AI development technique that treats LLM context like memory, rotating to fresh context before pollution builds up.

Core Principle

The malloc/free Problem:

• Reading files, tool outputs, conversation = malloc() (allocates context)
• There is no free() - context cannot be selectively released
• Only way to free: start a new conversation

Ralph's Solution: Deliberately rotate to fresh context before pollution builds up. State lives in files and git, not in the LLM's memory.

When to Use

Use Ralph Wiggum when:

• Working on complex, multi-step tasks
• Context window is filling up (>60k tokens)
• Agent is repeating failed attempts
• You need autonomous iteration on a task
• Context pollution is causing confusion

Setup

1. Create State Files

mkdir -p .ralph

Create these files:

.ralph/progress.md - What's been accomplished:

# Progress

## Completed
- [x] Initial setup
- [x] Basic structure created

## In Progress
- [ ] Feature implementation

## Next Steps
- Complete feature tests

.ralph/guardrails.md - Lessons learned (Signs):

# Guardrails (Signs)

## Sign: Check imports before adding
- **Trigger**: Adding a new import statement
- **Instruction**: First check if import already exists in file
- **Added after**: Duplicate import caused build failure

RALPH_TASK.md - Task definition with checkboxes:

---
task: Build feature X
test_command: "npm test"
---

# Task: Feature X

## Success Criteria

1. [ ] Feature works correctly
2. [ ] Tests pass
3. [ ] Documentation updated

## Context
- Use framework Y
- Follow pattern Z

2. Initialize Git (if not already)

git init
git add .ralph/ RALPH_TASK.md
git commit -m "ralph: initialize task"

The Loop

Iteration Process

1. Read State (not from previous context):

   • Read RALPH_TASK.md for task definition
   • Read .ralph/progress.md for what's done
   • Read .ralph/guardrails.md for lessons learned
   • Check git history for recent changes

2. Work on Unchecked Criteria:

   • Focus on [ ] items in RALPH_TASK.md
   • Follow guardrails from .ralph/guardrails.md
   • Make incremental progress

3. Commit Progress:

   git add -A
   git commit -m "ralph: [criterion] - description"
   

4. Update State Files:

   • Update .ralph/progress.md with accomplishments
   • If errors occur, add to .ralph/guardrails.md

5. Monitor Context:

   • Track token usage (approximate)
   • At ~70k tokens: warn to wrap up current work
   • At ~80k tokens: ROTATE to fresh context

Context Rotation

When approaching token limits:

1. Commit all work:

   git add -A
   git commit -m "ralph: checkpoint before rotation"
   git push  # if remote exists
   

2. Signal rotation: Output <ralph>ROTATE</ralph>

3. Next iteration: Start fresh, read state from files/git

Guardrails (Signs)

When something fails, add a "Sign" to .ralph/guardrails.md:

### Sign: [Brief description]
- **Trigger**: When this situation occurs
- **Instruction**: What to do differently
- **Added after**: Iteration X - what went wrong

Future iterations read guardrails first and follow them.

Completion Detection

Task is complete when:

1. All [ ] in RALPH_TASK.md are [x]
2. Agent outputs <ralph>COMPLETE</ralph>
3. All tests pass (if test_command specified)

Gutter Detection

Detect when stuck:

• Same command failed 3+ times → GUTTER
• Same file written 5+ times in short period → GUTTER
• Agent outputs <ralph>GUTTER</ralph>

When gutter detected:

1. Check .ralph/guardrails.md for patterns
2. Fix issue manually or add guardrail
3. Re-run iteration

Token Tracking

Approximate tracking:

• File read: ~1KB per 100 lines
• File write: ~1KB per 100 lines
• Tool calls: ~500 bytes each
• Conversation: ~100 bytes per message

Monitor and rotate before 80k tokens.

Workflow Example

# Iteration 1
# Read RALPH_TASK.md, progress.md, guardrails.md
# Work on first [ ] item
# Commit: git commit -m "ralph: implement feature X"
# Update progress.md
# Token count: ~45k → continue

# Iteration 2 (after rotation)
# Read RALPH_TASK.md, progress.md, guardrails.md (fresh context)
# Read git history to see previous work
# Work on next [ ] item
# Commit: git commit -m "ralph: add tests"
# Update progress.md
# Token count: ~78k → ROTATE signal

# Iteration 3 (fresh context)
# Read state files again
# Continue from git history
# Complete remaining items
# All [x] → COMPLETE

Best Practices

1. Commit frequently: After each meaningful change
2. Update progress.md: After completing each criterion
3. Add guardrails: When errors occur, document the lesson
4. Be specific: Each criterion should be testable and achievable
5. Rotate proactively: Don't wait until context is completely full
6. Use git history: Next iteration learns from commits, not context

Key Files Reference

Signals

Use these XML-like signals in your output:

• <ralph>ROTATE</ralph> - Request context rotation
• <ralph>COMPLETE</ralph> - Task is complete
• <ralph>GUTTER</ralph> - Agent is stuck, needs intervention
• <ralph>WARN</ralph> - Approaching token limit, wrap up current work

References

• Original Ralph technique - Geoffrey Huntley
• Context as memory - The malloc/free metaphor