Ralph Loops Skill

Autonomous multi-iteration build methodology. Based on Geoffrey Huntley's Ralph technique.

Architecture

Core insight: State lives in FILES, not the context window.

Each iteration gets a fresh context and follows: read progress → do ONE task → save state → repeat

This prevents context pollution — the #1 reason AI fails on complex builds. By iteration 15 of a normal session, the context is so polluted the AI edits files that don't exist. Ralph Loops solve this by externalizing all state.

┌─────────────────────────────────────────────────┐
│                  RALPH LOOP                       │
│                                                   │
│  INTERVIEW → PLAN → BUILD → DONE                 │
│  (5 iter)   (1 iter) (N iter) (signal)           │
│                    │                              │
│                    ▼                              │
│           progress.md ◀── Fresh context           │
│          (ground truth)    each iteration          │
└─────────────────────────────────────────────────┘

Phases

1. Interview (max 5 iterations)

• •Gather requirements from user
• •Ask clarifying questions
• •Output: specs files

2. Plan (1 iteration)

• •Read specs, create numbered implementation plan
• •Output: numbered task checklist in progress.md
• •Each task = ONE atomic unit of work

3. Build (N iterations)

• •Each iteration: read progress.md → find next unchecked task → do it → mark done → save
• •ONE task per iteration. Never two.
• •Screenshot after visual changes
• •Run tests/lint before marking done

4. Done

• •All tasks checked off
• •Emit RALPH_DONE signal
• •Final screenshot

Files

progress.md Structure

# Ralph Loop: [Project Name]
## Started: [timestamp]
## Status: IN_PROGRESS | RALPH_DONE

## Plan
- [ ] 1. First task (atomic, specific)
- [ ] 2. Second task
- [x] 3. Completed task
...

## Iteration Log
### Iteration 1 (YYYY-MM-DD HH:MM UTC)
- Task: #1 — description
- Result: Done/Failed
- Screenshot: /path/if/visual

Usage

Starting a Ralph Loop

1. •Create /data/ralph-loop-progress.md with plan (or let Interview phase create it)
2. •Set cron: every 30min, payload reads progress, does ONE task, saves state
3. •Or use sessions_spawn for each iteration
4. •Each iteration reads progress.md FIRST, finds next unchecked - [ ] task
5. •Does ONE task only, marks it - [x], logs iteration
6. •Takes screenshot if visual change
7. •Emits RALPH_DONE when all tasks are [x]

Cron Payload Template

Read /data/ralph-loop-progress.md. Find the next unchecked task (- [ ]). 
Do ONLY that one task. Mark it done (- [x]). 
Add an iteration log entry with timestamp.
If visual change, take a screenshot.
If ALL tasks are done, change Status to RALPH_DONE.
Do NOT do more than one task.

Iteration Prompt (what each iteration does)

1. Read /data/ralph-loop-progress.md
2. If Status = RALPH_DONE → reply "RALPH_DONE" and stop
3. Find first unchecked task (- [ ])
4. Execute ONLY that task
5. Mark it [x] in progress.md
6. Add iteration log entry with timestamp
7. If visual change → screenshot
8. If no unchecked tasks remain → set Status: RALPH_DONE

Key Rules

1. •ONE task per iteration — never two. This is non-negotiable.
2. •State lives in FILES — never trust context memory across iterations.
3. •Always read progress.md FIRST — before doing anything.
4. •Always update progress.md AFTER — mark task done, log iteration.
5. •Screenshot after visual changes — proof of progress.
6. •Kill and restart if stuck — failures are data, not bugs. Tune prompts.
7. •Numbered guardrails — hard priorities prevent scope creep.
8. •Tests before marking done — mistakes don't compound.

When to Use Ralph

Economics

Reference

See references/ralph-article.txt for the full methodology article. Based on Geoffrey Huntley's Ralph technique (ghuntley.com/ralph).