Ralph Method

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

1. One iteration = One story = One commit
2. Each story must be completable in a single AI iteration (5-30 minutes of work)
3. Stories are ordered by dependency (infrastructure first, consumers last)
4. Every story ends with build/test verification
5. 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

Database Change

React Component

Refactoring

Configuration Change

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

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.