Ralph Wiggum Method
The Ralph Wiggum Method is an autonomous AI coding loop that ships features while you sleep. It breaks complex tasks into atomic user stories that can each be completed in a single AI iteration.
Core Principles
- One iteration = One story = One commit
- Each story must be completable in a single AI iteration (5-30 minutes of work)
- Stories are ordered by dependency (infrastructure first, consumers last)
- Every story ends with build/test verification
- The loop runs autonomously until all stories pass
Story Atomicity Rules
A story is atomic when:
- It can be committed independently without breaking the build
- It leaves the codebase in a working state
- It has clear, verifiable "done" criteria
- It doesn't require human intervention mid-way
- It can be code-reviewed as a single logical change
Story Decomposition Patterns
API Endpoint
| Priority | Story | Purpose |
|---|
| 1 | Create schema/types | Define data structures |
| 2 | Create service layer | Business logic |
| 3 | Create route handler | HTTP interface |
| 4 | Add integration test | Verification |
Database Change
| Priority | Story | Purpose |
|---|
| 1 | Create migration file | Schema change |
| 2 | Update model/entity | Code representation |
| 3 | Update seed data | Test data |
| 4 | Update consuming code | Integration |
React Component
| Priority | Story | Purpose |
|---|
| 1 | Create component skeleton | Structure |
| 2 | Add state/logic | Behavior |
| 3 | Add styling | Appearance |
| 4 | Add tests | Quality |
Refactoring
| Priority | Story | Purpose |
|---|
| 1 | Add new implementation alongside old | Parallel path |
| 2 | Migrate consumers one by one | Gradual switch |
| 3 | Remove old implementation | Cleanup |
Configuration Change
| Priority | Story | Purpose |
|---|
| 1 | Add environment variables | Define config |
| 2 | Create/update config file | Structure config |
| 3 | Update consuming code | Use config |
prd.json Schema
{
"branchName": "ralph/feature-name",
"taskDescription": "One-line summary of the task",
"projectContext": {
"framework": "e.g., Next.js, .NET",
"testCommand": "e.g., npm test, dotnet test",
"buildCommand": "e.g., npm run build, dotnet build"
},
"userStories": [
{
"id": "US-001",
"title": "Short descriptive title",
"description": "What to implement in detail",
"acceptanceCriteria": [
"Specific, verifiable criterion 1",
"Specific, verifiable criterion 2",
"Build/test passes"
],
"priority": 1,
"passes": false,
"notes": "Hints, gotchas, references to existing code"
}
]
}
Field Descriptions
- branchName: Git branch for all work (format:
ralph/<feature-name>)
- taskDescription: One-line summary for quick context
- projectContext: Build/test commands and framework info
- userStories: Array of atomic stories in dependency order
- id: Unique identifier (US-001, US-002, etc.)
- title: Short title for commit messages
- description: Full implementation details
- acceptanceCriteria: Verifiable conditions for "done"
- priority: Execution order (1 = first)
- passes: Set to true when story is complete
- notes: Additional context, gotchas, file references
Anti-Patterns to Avoid
Vague Stories
- BAD: "Update all files"
- GOOD: "Update UserController to use new AuthService"
Unbounded Scope
- BAD: "Fix bugs as found"
- GOOD: "Fix null reference in UserService.GetById"
Circular Dependencies
- BAD: Story 3 depends on Story 5 which depends on Story 3
- GOOD: Linear dependency chain
Too Large
- BAD: "Implement entire authentication system"
- GOOD: Split into: schema, service, middleware, routes, tests
Missing Verification
- BAD: Story with no acceptance criteria
- GOOD: Every story ends with "Build succeeds" or "Tests pass"
Story Sizing Guidelines
| Size | Time | Examples |
|---|
| XS | 5-10 min | Add config value, create empty file, update import |
| S | 10-20 min | Create simple function, add basic test, update route |
| M | 20-30 min | Create service class, add migration, implement handler |
| L | 30+ min | TOO BIG - split into smaller stories |
Verification Commands
Every story should end with verification. Common patterns:
# JavaScript/TypeScript
npm run build && npm test
# .NET
dotnet build && dotnet test
# Python
pytest && python -m py_compile src/*.py
# Go
go build ./... && go test ./...
Progress Tracking
The progress.txt file tracks completed stories:
# Progress: feature-name
# Total stories: 5
Current story: 3
Completed: 2
---
# Story log
[2025-01-10 10:00] US-001: Create user entity - PASSED
[2025-01-10 10:15] US-002: Add user repository - PASSED
Commit Message Format
story US-XXX: <title>
<description of what was done>
Example:
story US-001: Create user entity
Added UserEntity with id, email, and created_at fields.
Configured EF Core mapping in ApplicationDbContext.
