# Ralph Wiggum > Autonomous task completion loop with PRD tracking and LLM memory - Skill: `majiayu000/ralph-wiggum-3` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add majiayu000/ralph-wiggum-3` - Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/ralph-wiggum-3/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning - Author: majiayu000 (https://skillmd.com/u/majiayu000) - Updated: 2026-09-09 - Page: https://skillmd.com/skills/majiayu000/ralph-wiggum-3 --- # Ralph Wiggum Technique ## Overview The Ralph Wiggum technique is a simple but powerful pattern for autonomous AI-driven development: 1. **PRD (prd.json)**: JSON file with user stories, each having a `passes` boolean 2. **Progress file (progress.txt)**: LLM memory between iterations 3. **Loop**: Run Claude Code repeatedly until all tasks pass Named after Ralph Wiggum from The Simpsons - simple but effective. > "Me fail English? That's unpossible!" - Ralph Wiggum ## Why It Works ### The Problem with AI Coding - LLMs lose context between sessions - No persistent memory of what worked/failed - Tendency to declare victory without verification - Complex orchestration systems add overhead ### The Solution 1. **Structured task list (JSON)**: Machine-readable, hard for LLM to corrupt 2. **Progress file**: Persistent memory across iterations 3. **Verification gate**: MUST pass all checks before marking complete 4. **Git commits**: Checkpoint after each success 5. **Simple loop**: No complex orchestration needed ## Components ### 1. PRD File (plans/prd.json) ```json { "project": "My Project", "version": "1.0.0", "user_stories": [ { "id": "US-001", "epic": "Authentication", "title": "User can sign up with email", "description": "As a user, I want to sign up so I can access the app", "priority": "critical", "acceptance_criteria": [ "Email validation works", "Password strength checked", "Confirmation email sent" ], "verification": { "type_check": true, "lint": true, "unit_tests": true, "e2e_tests": true, "build": true }, "passes": false, "last_attempt": null, "attempt_count": 0, "depends_on": [] } ], "metadata": { "total_stories": 1, "passing_stories": 0 } } ``` ### Key Fields | Field | Purpose | |-------|---------| | `passes` | Boolean gate - only true after verification | | `priority` | Execution order: critical > high > medium > low | | `depends_on` | Task IDs that must pass first | | `acceptance_criteria` | Specific requirements to implement | | `attempt_count` | Tracks failed attempts (for debugging) | ### 2. Progress File (plans/progress.txt) Append-only file with session entries: ```markdown # Ralph Wiggum Progress Log # Project: my-project # Created: 2026-01-07T10:00:00Z --- ## Session 1: 2026-01-07T10:30:00Z **Task**: US-001 - User can sign up with email **Status**: IN_PROGRESS ### Work Done - Created SignUpForm component at apps/web/src/components/auth/SignUpForm.tsx - Added zod schema for email validation ### Issues Encountered - useAuth hook missing return type annotation ### Learnings - Always add explicit return types to custom hooks - Email regex pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/ ### Next Steps 1. Fix useAuth hook return type 2. Add unit tests for SignUpForm 3. Run full verification --- ## Session 2: 2026-01-07T11:00:00Z **Task**: US-001 - User can sign up with email **Status**: COMPLETED ### Work Done - Fixed useAuth return type - Added comprehensive unit tests - All verification passed ### Learnings - Vitest mocking pattern for Supabase auth ### Next Steps - Move to US-002 ``` ### 3. Verification Pipeline ALL must pass before marking `passes: true`: ```bash pnpm turbo run type-check # TypeScript compilation pnpm turbo run lint # ESLint + Ruff linting pnpm turbo run test # Unit tests (Vitest/Pytest) pnpm turbo run build # Production build pnpm --filter=web test:e2e # Playwright E2E tests ``` ## Workflow Diagram ``` ┌─────────────────────────────────────────┐ │ Start Iteration N │ └─────────────────┬───────────────────────┘ │ ▼ ┌─────────────────────────────────────────┐ │ All tasks passed? │ │ ├─ Yes → Exit (Project Complete!) │ │ └─ No → Continue │ └─────────────────┬───────────────────────┘ │ ▼ ┌─────────────────────────────────────────┐ │ Find highest priority unpassed task │ │ (respecting depends_on constraints) │ └─────────────────┬───────────────────────┘ │ ▼ ┌─────────────────────────────────────────┐ │ Load context: │ │ - Read prd.json for task details │ │ - Read progress.txt for learnings │ └─────────────────┬───────────────────────┘ │ ▼ ┌─────────────────────────────────────────┐ │ Work on task: │ │ - Implement per acceptance criteria │ │ - Add/update tests │ │ - Follow project conventions │ └─────────────────┬───────────────────────┘ │ ▼ ┌─────────────────────────────────────────┐ │ Run verification pipeline │ │ type-check → lint → test → build → e2e │ └─────────────────┬───────────────────────┘ │ ┌─────────┴─────────┐ │ │ ▼ ▼ ┌───────────────┐ ┌───────────────┐ │ All PASS │ │ Any FAIL │ └───────┬───────┘ └───────┬───────┘ │ │ ▼ ▼ ┌───────────────┐ ┌───────────────┐ │ Set passes: │ │ Increment │ │ true in PRD │ │ attempt_count │ │ │ │ │ │ Git commit │ │ Record issues │ └───────┬───────┘ └───────┬───────┘ │ │ └─────────┬─────────┘ │ ▼ ┌─────────────────────────────────────────┐ │ Append session to progress.txt │ └─────────────────┬───────────────────────┘ │ ▼ ┌─────────────────────────────────────────┐ │ Continue to Iteration N+1 │ └─────────────────────────────────────────┘ ``` ## Invocation ### Initialize (First Time) ```bash # Unix/Mac/WSL ./scripts/ralph.sh --init # Windows PowerShell .\scripts\ralph.ps1 -Init # Creates: # - plans/prd.json (template) # - plans/progress.txt (empty) # - plans/ralph-prompt.md (iteration prompt) ``` ### Run the Loop ```bash # Unix/Mac/WSL ./scripts/ralph.sh 50 # Max 50 iterations # Windows PowerShell .\scripts\ralph.ps1 -MaxIterations 50 # Claude Code command /ralph run 50 ``` ## Best Practices ### 1. Small, Focused Tasks Keep user stories to 1-2 hour scope: ```json // Good { "title": "Add email validation to sign-up form" } // Too big { "title": "Implement entire authentication system" } ``` ### 2. Specific Acceptance Criteria Vague criteria lead to incomplete implementations: ```json // Good { "acceptance_criteria": [ "Email format validated with regex", "Error message shown for invalid email", "Submit button disabled until valid" ] } // Too vague { "acceptance_criteria": [ "Form works properly" ] } ``` ### 3. Use Dependencies Order tasks logically: ```json { "id": "US-002", "title": "User can log in", "depends_on": ["US-001"] // Sign-up must work first } ``` ### 4. Read Progress Before Working Check what was learned in previous iterations: ```markdown ### Learnings - Vitest mocking pattern for Supabase: vi.mock('@supabase/ssr') - Always await signUp() before checking error state ``` ### 5. Commit After Each Success Creates checkpoints for recovery: ```bash git log --oneline # feat(US-003): User can reset password # feat(US-002): User can log in # feat(US-001): User can sign up with email ``` ### 6. Escalate Repeated Failures If `attempt_count >= 3`: - Stop working on task - Record blocker in progress.txt - Move to next available task - Flag for human review ## Integration with Existing Systems ### Long-Running Agents Ralph follows the same patterns as `apps/backend/src/agents/long_running/`: | Ralph | Long-Running | |-------|--------------| | `progress.txt` | `ProgressFile` class | | `prd.json` | `FeatureManager` | | Session entries | `SessionProgress` | ### Orchestrator Delegation The orchestrator can hand off to Ralph for autonomous completion: ```python async def handle_large_feature(feature_description: str): # Create PRD from feature description prd = generate_prd(feature_description) save_prd("plans/prd.json", prd) # Delegate to Ralph return await delegate_to_agent("ralph-wiggum", { "prd_path": "plans/prd.json", "max_iterations": 50 }) ``` ### Verification Agent Uses the same verification-first principles: - No self-attestation - Run actual commands - All checks must pass ## Example Session Output ``` ============================================ Ralph Wiggum Technique Autonomous Task Completion Loop ============================================ >>> Checking prerequisites... Claude CLI found PRD file found All prerequisites OK ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Iteration 1: US-001 User can sign up with email ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ >>> Invoking Claude Code... [Claude implements sign-up form] >>> Running verification pipeline... Running type check... Type check: PASS Running lint... Lint: PASS Running tests... Tests: PASS Running build... Build: PASS Running E2E tests... E2E: PASS Verification passed! Marking US-001 as complete. [Auto-commit: feat(US-001): User can sign up with email] ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Iteration 2: US-002 User can log in with email ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ... ============================================ Summary ============================================ Iterations: 5 Tasks Completed: 5 Progress: 5/5 tasks complete Duration: 00:45:23 All tasks complete! Project finished in 5 iterations. ``` ## Australian Context All implementations follow Australian defaults: - en-AU spelling (colour, organisation, behaviour) - DD/MM/YYYY date format - AUD currency formatting where applicable - Privacy Act 1988 compliance considerations for user data ## References - [Original Ralph Article](https://ghuntley.com/ralph/) by Jeffrey Huntley - [Matt Pocock Video](https://www.youtube.com/watch?v=_IK18goX4X8) - [Anthropic Engineering Blog](https://www.anthropic.com/engineering)