Dev Ralph Loop

Announce: "I'm using dev-ralph-loop to set up verification loops."

Before starting ANY ralph loop, you MUST load the TDD skill to remember the testing gates and task reframing:

Read ${CLAUDE_PLUGIN_ROOT}/skills/dev-tdd/SKILL.md and follow its instructions.

This loads:

• Task reframing (your job is writing tests, not features)
• The Execution Gate (6 mandatory gates before E2E testing)
• GATE 5: READ LOGS (mandatory - cannot skip)
• The Iron Law of TDD (test-first approach)

Read dev-tdd skill content now before proceeding with ralph loops.

Contents

• The Iron Law
• Per-Task Pattern
• Starting a Loop
• Inside the Loop
• Completing a Loop
• Example: Multi-Task Feature
• Rationalizations

Ralph Loop Pattern

ONE LOOP PER TASK. NOT ONE LOOP PER FEATURE. This is not negotiable.

A single feature-level loop provides ZERO per-task enforcement. You can just move to the next task without the loop actually gating anything.

Each task in PLAN.md gets its own ralph loop with its own completion promise.

The Per-Task Pattern

For task N in PLAN.md (1, 2, 3, ...):
    1. Start ralph loop for task N
    2. Inside loop: spawn Task agents, iterate until done
    3. Output promise → loop ends
    4. Move to task N+1, start NEW ralph loop

Why per-task loops?

• Feature loops don't enforce task completion
• Without a loop per task, you can just... move on
• Each task needs its own completion gate
• The promise is your proof that the task is done

Starting a Loop

IMPORTANT: Avoid parentheses () in the prompt - they break zsh argument parsing. Use dashes or brackets instead.

For Implementation Tasks

Skill(skill="ralph-loop:ralph-loop", args="Task N: [TASK NAME] --max-iterations 10 --completion-promise TASKN_DONE")

For Debug Tasks

Skill(skill="ralph-loop:ralph-loop", args="Debug: [SYMPTOM] --max-iterations 15 --completion-promise FIXED")

Parameters

Inside the Loop

Each iteration follows this pattern:

1. Spawn Task Agent

Task(subagent_type="general-purpose", prompt="""
[TASK-SPECIFIC INSTRUCTIONS]

Context:
- Read .planning/LEARNINGS.md for prior attempts
- Read .planning/SPEC.md for requirements
- Read .planning/PLAN.md for approach

Report back: what was done, results, any blockers.
""")

2. Verify Results

After Task agent returns:

• Check if the work is actually complete
• Verify tests pass (for implementation)
• Verify bug is fixed (for debugging)

3. Decide: Promise or Iterate

If complete: Output the promise

<promise>TASKN_DONE</promise>

If incomplete: Do NOT output promise. Spawn another Task agent to continue.

You may ONLY output the promise when the statement is COMPLETELY AND UNEQUIVOCALLY TRUE.

The promise is a claim that:

• For implementation: "This task's tests pass. The implementation is complete."
• For debugging: "The bug is fixed. Regression test passes."

You may NOT output the promise to:

• "Move on" to the next task
• "Try something else"
• Skip verification

If the promise isn't true, don't output it. Keep iterating.

Completing a Loop

When you output the promise, the ralph loop ends. Then:

1. Update PLAN.md - Mark task complete:

   - [ ] Task N: Description  →  - [x] Task N: Description
   

2. Log to LEARNINGS.md - What was done, any discoveries
3. Immediately start next task's loop - Same response, no pause

After outputting a promise, you MUST start the next task within the SAME RESPONSE.

Not "should". Not "recommended". MUST.

The only valid stopping points:

1. ALL tasks in PLAN.md are marked [x] complete
2. You hit a blocker that requires user input (be specific about what you need)
3. User explicitly interrupted

Finishing one task is NOT a stopping point. The user is waiting for the FEATURE, not status updates.

Example: Multi-Task Feature

## Task 1: Create types
Skill(skill="ralph-loop:ralph-loop", args="Task 1: Create types --max-iterations 5 --completion-promise TASK1_DONE")

[Spawn Task agent → implements types]
[Verify: tsc --noEmit passes]

<promise>TASK1_DONE</promise>

[Update PLAN.md: - [ ] Task 1 → - [x] Task 1]
[Log to LEARNINGS.md]
[IMMEDIATELY continue to Task 2 - same response]

## Task 2: Add service method
Skill(skill="ralph-loop:ralph-loop", args="Task 2: Add service method --max-iterations 10 --completion-promise TASK2_DONE")

[Spawn Task agent → implements method]
[Verify: tests fail → iterate]
[Spawn Task agent → fixes tests]
[Verify: tests pass]

<promise>TASK2_DONE</promise>

[Update PLAN.md: - [ ] Task 2 → - [x] Task 2]
[Log to LEARNINGS.md]
[IMMEDIATELY continue to Task 3 - same response]

## Task 3: Add route handler
Skill(skill="ralph-loop:ralph-loop", args="Task 3: Add route handler --max-iterations 10 --completion-promise TASK3_DONE")

[Spawn Task agent → implements route]
[Verify: integration test passes]

<promise>TASK3_DONE</promise>

[Update PLAN.md: - [ ] Task 3 → - [x] Task 3]
[Log to LEARNINGS.md]

## All tasks complete - NOW you can stop

Rationalization Prevention

These thoughts mean STOP—you're about to skip enforcement:

Each task needs its own ralph loop. One feature loop provides ZERO per-task enforcement.

After outputting a promise: (1) Update PLAN.md, (2) Log to LEARNINGS.md, (3) Start next task's loop. All in the same response.

When NOT to Use Ralph Loops

Ralph loops are for:

• Implementation tasks (dev-implement)
• Bug fixes (dev-debug)

Ralph loops are NOT for:

• Exploration (dev-explore)
• Design (dev-design)
• Data science (ds uses output-first verification instead)
• Review phases (dev-review, ds-review)

Visual Tasks

For tasks that produce rendered visual output (slides, charts, UI), use visual-verify instead of a plain ralph loop. Visual-verify wraps the ralph-loop pattern with render → look-at → fix steps:

Read ${CLAUDE_PLUGIN_ROOT}/skills/visual-verify/SKILL.md and follow its instructions.

Integration

This skill is invoked by:

• dev-implement - for standard implementation tasks
• dev-debug - for bug investigation and fixes
• visual-verify - wraps ralph-loop for visual output tasks

After all tasks complete, proceed to the next phase of the parent workflow.