Iterative Loop Engine: The Meta-Pattern

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:

Quick Domain Selection

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

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:

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

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:

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:

---