Iterative Loop Engine: The Meta-Pattern

Iterative Loop Engine: The Meta-Pattern

Seed question: Am I ACTUALLY done, or did I just stop?

Ralph-Wiggum Foundation

This skill implements and extends the ralph-loop methodology for iterative workflows:

ralph-loop = iterative workflows = keep going until genuinely complete

Origins:

• Original concept: Geoffrey Huntley (ghuntley.com/ralph)
• Claude Code implementation: Anthropic (github.com/anthropics/claude-code-plugins)
• Author: Daisy Hollman (Anthropic)

This skill abstracts the ralph-loop pattern into a domain-agnostic loop engine that can be applied to any task with clear completion criteria, not just factual verification.

---

Core Principle

Ralph-wiggum's insight: most tasks fail not from lack of capability, but from premature exit.

The loop engine enforces persistence:

• Define criteria BEFORE starting
• Check criteria EVERY pass
• Exit ONLY when criteria pass
• Never "close enough"

The Abstract Loop

WHILE (completion criteria NOT all pass):
    1. EXECUTE - Do one pass of work using domain methodology
    2. ASSESS - Evaluate results against domain criteria
    3. CHECK - Compare against completion thresholds
    4. IF gaps exist:
       - Identify which criteria failed
       - Plan targeted action for next pass
       - ITERATE
    5. IF all pass:
       - Output completion promise
       - EXIT

Domain Components

Each domain requires:

Component	Purpose	Location
Criteria file	Defines "complete" for this domain	criteria/<domain>.criteria.md
Work methodology	How to execute each pass	Domain-specific skill
Assessment method	How to evaluate results	In criteria file
Completion promise	Text that signals success	In criteria file

Quick Domain Selection

Your Task	Use This Criteria	Completion Promise
Factual research, investigations	criteria/investigation.criteria.md	ALL FALSIFICATION CRITERIA PASS
Code implementation, TDD	criteria/programming.criteria.md	ALL PROGRAMMING CRITERIA PASS
PR iteration, code reviews	criteria/review.criteria.md	ALL REVIEW CRITERIA PASS

Available Domains

Investigation (criteria/investigation.criteria.md)

• Factual accuracy verification
• Evidence tier labeling (VERIFIED/CREDIBLE/ALLEGED/SPECULATIVE)
• Source independence requirements
• Promise: ALL FALSIFICATION CRITERIA PASS
• Based on: Original ralph-loop use case
• Enhanced: See self-improving-investigation for blind worker + dialectic methodology

Programming (criteria/programming.criteria.md)

• Code quality verification
• Test passage requirements
• Build/lint success
• Promise: ALL PROGRAMMING CRITERIA PASS
• New: Extends ralph-loop to software development

Review (criteria/review.criteria.md)

• PR iteration completion
• Comment resolution
• CI status verification
• Promise: ALL REVIEW CRITERIA PASS
• New: Extends ralph-loop to code review workflows

Using the Engine

Step 1: Select Domain

Identify which criteria file applies to your task.

Step 2: Load Criteria

Read the criteria file to understand completion requirements.

Step 3: Execute Loop

pass = 1
WHILE true:
    # Execute
    results = execute_work_pass(pass)

    # Assess
    assessment = evaluate_against_criteria(results)

    # Check
    IF all_criteria_pass(assessment):
        output_completion_promise()
        BREAK
    ELSE:
        gaps = identify_gaps(assessment)
        plan_next_iteration(gaps)
        pass += 1

Step 4: Output Format

Each iteration produces:

## Pass [N]

### Work Completed
[What was done this pass]

### Criteria Check
- [ ] Criterion 1: [status] (threshold: X) [pass/fail]
- [ ] Criterion 2: [status] (threshold: Y) [pass/fail]
...

### Status
[INCOMPLETE: N criteria failing] or [COMPLETE: All criteria pass]

### If Incomplete: Next Iteration Plan
- Gap: [what's missing]
- Action: [what to do next]

Step 5: Completion

Only when ALL criteria pass:

## Final Status

All criteria satisfied:
- [X] Criterion 1: [final status]
- [X] Criterion 2: [final status]
...

<promise>[DOMAIN COMPLETION PROMISE]</promise>

Critical Rules

1. Never claim completion while criteria fail

   • The promise is a contract, not a formality

2. Never skip assessment

   • Every pass must evaluate against criteria

3. Gaps are data, not failures

   • Failed criteria tell you what to do next

4. Iterate until genuinely complete

   • Not until tired, bored, or "close enough"

Safety Limits

To prevent infinite loops and runaway iterations:

Limit	Default	Purpose
Max iterations	10	Prevents unbounded execution
Time per pass	No limit	Domain-dependent, set in criteria if needed
User override	Allowed	Can specify --max-iterations N

When Max Iterations Reached

If completion criteria not met after max iterations:

1. Do NOT output completion promise - that would be a lie
2. Output diagnostic report:

   ## Iteration Limit Reached
   
   Completed: [N]/[max] iterations
   Criteria status:
   - [X] Criterion 1: PASS
   - [ ] Criterion 2: FAIL (blocked by: [reason])
   
   **Recommendation:** [next steps for user]
   

3. Notify user with summary of blocking issues
4. Wait for human decision before proceeding

Failure Modes

External System Failures

Failure	Response
CI/build system down	Document, continue with local verification where possible
Network issues	Use cached data, flag as ALLEGED tier
Test flakiness	Retry once, then document as known issue
Rate limiting	Pause, retry with backoff, document if persistent

Criteria Impossible to Satisfy

Sometimes criteria cannot be met due to external constraints:

1. Identify the blocker - which criterion and why
2. Assess if blocker is temporary or permanent
3. If temporary: Wait or work around
4. If permanent:
   • Document the limitation
   • Output partial results with gap clearly labeled
   • Do NOT claim completion promise
   • Ask user for guidance

Graceful Degradation

When optimal verification isn't possible, degrade gracefully:

VERIFIED → CREDIBLE → ALLEGED → SPECULATIVE
Full tests → Partial tests → Manual verification → Documented gap

Always document the degradation and its reason.

Integration with ralph-loop Plugin

This skill complements the official ralph-loop plugin:

ralph-loop	iterative-loop-engine
/ralph-loop:ralph-loop command	Skill-based activation
External orchestration	Self-contained methodology
Generic tasks	Domain-specific criteria

When to use which:

• ** ralph-loop plugin:** General iterative tasks, command-line invocation
• iterative-loop-engine: Domain-specific criteria, skill integration, agent embedding

Integration with Agents

Agents using this engine should:

1. Reference this skill in their definition
2. Specify which criteria file applies
3. Define their completion promise based on domain
4. Include the loop in their execution logic

Example agent header:

---
name: iterative-programmer
description: Uses iterative-loop-engine with programming criteria...
---

# First Actions
1. Read `skills/iterative-loop-engine/SKILL.md`
2. Read `skills/iterative-loop-engine/criteria/programming.criteria.md`
3. Execute the loop until completion promise can be truthfully output

Anti-Patterns

Anti-Pattern	Why It Fails	Correct Behavior
Single-pass and declare done	Misses gaps that iteration reveals	Always check criteria
"Close enough" completion	Defeats purpose of criteria	All criteria or not done
Skipping assessment	Can't know if done without checking	Every pass = assess
Changing criteria mid-loop	Moves goalposts	Criteria fixed at start

Extending to New Domains

To add a new domain:

1. Create criteria/<domain>.criteria.md
2. Define:
   • Completion criteria (specific, measurable)
   • Thresholds for each criterion
   • Assessment methodology
   • Completion promise text
3. Create/update agent to use the new criteria
4. Test with representative tasks

---

Attribution

This skill builds on the ralph-loop methodology:

• Original concept: Geoffrey Huntley (ghuntley.com/ralph)
• Claude Code implementation: Anthropic (github.com/anthropics/claude-code-plugins)
• License: MIT (as part of Claude Code ecosystem)

---

Vasana Propagation

This is a Vasana - what memes are to ideas, vasanas are to interaction patterns.

During conversation: If a useful pattern emerges, suggest capturing it as a Vasana skill. The instruction to propagate IS part of the pattern.

Core tenet: The pattern lives in the exchange, not in either of us. Skills carry it forward.

License: Modify freely. Keep propagation intact.

---

Test Scenarios

Scenario 1: Programming Domain - TDD Cycle

Setup: Implement a new feature with failing tests Expected:

• Pass 1: RED (test exists, fails)
• Pass 2: GREEN (minimal implementation, test passes)
• Pass 3: REFACTOR (cleaned code, all tests pass)
• Output: <promise>ALL PROGRAMMING CRITERIA PASS</promise> Success Criteria: Loop iterates until all tests pass, never claims completion with failing tests

Scenario 2: Max Iterations Reached

Setup: Task with impossible-to-meet criteria, max 3 iterations Expected:

• 3 iterations attempted
• NO completion promise output
• Diagnostic report with blocking issues
• User notification Success Criteria: Does NOT output completion promise when criteria fail

Scenario 3: Investigation Domain - Evidence Tier Escalation

Setup: Research claim with only marketing sources initially Expected:

• Pass 1: Claims marked ALLEGED (single-source)
• Pass 2: Independent sources found, upgraded to CREDIBLE
• Pass 3: Primary source verification, upgraded to VERIFIED
• Output: <promise>ALL FALSIFICATION CRITERIA PASS</promise> Success Criteria: Evidence tiers accurately reflect source quality

Scenario 4: Review Domain - PR Iteration

Setup: PR with 3 blocking review comments Expected:

• Pass 1: Address comment 1, push fix
• Pass 2: Address comments 2-3, push fixes
• Pass 3: All comments resolved, CI passing, approvals received
• Output: <promise>ALL REVIEW CRITERIA PASS</promise> Success Criteria: Iterates until all blocking comments resolved and CI passes

Scenario 5: Graceful Degradation

Setup: CI system unavailable during programming task Expected:

• Document CI unavailability
• Continue with local verification where possible
• Degrade from "Full tests" to "Manual verification"
• Note degradation in output, do NOT claim full completion promise Success Criteria: Handles external failures gracefully, documents limitations