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:

   bash

   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:

   bash

   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