/iterate - Ralph Iterate Pattern (v3.0)

Execute tasks iteratively with automatic quality validation until VERIFIED_DONE signal.

v2.88 Key Changes (MODEL-AGNOSTIC)

• Model-agnostic: Uses model configured in ~/.claude/settings.json or CLI/env vars
• No flags required: Iterations use the configured default model
• Flexible: Works with GLM-5, Claude, Minimax, or any configured model
• Settings-driven: Model selection via ANTHROPIC_DEFAULT_*_MODEL env vars

v2.87 Key Changes (UNIFIED SKILLS MODEL)

• Skills/Commands unification: All commands now use SKILL.md format
• Single source of truth: Skills live in repo, symlinked globally
• Version alignment: All skills updated to v2.87.0
• Documentation consolidated: Architecture docs in docs/architecture/

Overview

The Ralph Loop is a continuous execution pattern that iterates through EXECUTE -> VALIDATE -> QUALITY CHECK cycles until the task passes all quality gates or reaches the iteration limit.

+------------------------------------------------------------------+
|                    RALPH LOOP PATTERN                             |
+------------------------------------------------------------------+
|                                                                   |
|   +----------+    +--------------+    +-----------------+         |
|   | EXECUTE  |--->|   VALIDATE   |--->| Quality Passed? |         |
|   |   Task   |    | (hooks/gates)|    +--------+--------+         |
|   +----------+    +--------------+             |                  |
|                                          NO <--+--> YES           |
|                                           |         |             |
|                          +----------------+         |             |
|                          v                          v             |
|                   +------------+          +---------------+       |
|                   |  ITERATE   |          | VERIFIED_DONE |       |
|                   | (max 15/30)|          |   (output)    |       |
|                   +-----+------+          +---------------+       |
|                         |                                         |
|                         +----------> Back to EXECUTE              |
|                                                                   |
+------------------------------------------------------------------+

When to Use

Use /iterate when:

1. Iterative refinement needed - Code requires multiple passes to meet quality standards
2. Quality gates must pass - TypeScript, ESLint, tests, linting must all pass
3. Automated validation - Let the loop handle retries automatically
4. Complex implementations - Multi-file changes that need coordination
5. Research tasks - Gathering information until complete

DO NOT use for:

• Simple one-shot tasks (use direct claude call)
• Tasks already in orchestration flow (redundant)
• Spec refinement workflows (use /adversarial)

Iteration Limits

Model	Max Iterations	Cost vs Claude	Quality	Use Case
Claude (Sonnet/Opus)	15	100% (baseline)	85-90% SWE-bench	Complex reasoning, high accuracy
GLM-5	30	~10%	80%+ SWE-bench	Standard tasks (2x multiplier)
MiniMax M2.1	30	~8%	74% SWE-bench	Standard tasks (2x multiplier)

Model Selection

Default Mode (Claude)

ralph iterate "implement OAuth2 authentication"

Uses Claude Sonnet with 15 iteration limit:

• Best for: Complex features, security-critical code, architectural changes
• Cost: Standard Claude pricing
• Quality: 85%+ SWE-bench accuracy

GLM-5 Mode (--with-glm5 flag)

ralph iterate "implement OAuth2 authentication" --with-glm5

Uses GLM-5 with 30 iteration limit:

• Best for: Standard features, refactoring, testing, documentation
• Cost: ~10% of Claude cost
• Quality: 80%+ SWE-bench accuracy

MiniMax Mode (--mmc flag)

ralph iterate --mmc "implement OAuth2 authentication"

Uses MiniMax M2.1 with 30 iteration limit:

• Best for: Non-critical features, exploratory research
• Cost: ~8% of Claude cost
• Quality: 74% SWE-bench accuracy

CLI Execution

# Claude mode (15 iterations)
ralph iterate "implement user authentication with JWT"

# GLM-5 mode (30 iterations)
ralph iterate "refactor database queries" --with-glm5

# MiniMax mode (30 iterations)
ralph iterate --mmc "refactor database queries to use TypeORM"

# Complex task with specific requirements
ralph iterate "add rate limiting to API endpoints with Redis"

Task Tool Invocation (Swarm Mode)

IMPORTANT: /iterate uses swarm mode by default with full multi-agent coordination.

Task:
  subagent_type: "general-purpose"
  model: "sonnet"
  run_in_background: true
  max_iterations: 15
  description: "Loop execution with swarm mode"
  team_name: "iterate-execution-team"
  name: "iterate-lead"
  mode: "delegate"
  prompt: |
    Execute the following task iteratively until VERIFIED_DONE:

    Task: $ARGUMENTS

    Ralph Loop pattern:
    1. EXECUTE - Implement the task
    2. VALIDATE - Run quality gates (tsc, eslint, tests)
    3. CHECK - Did all gates pass?
       - YES -> VERIFIED_DONE
       - NO -> ITERATE (max 15)

    Output: Final implementation + quality report

Agent Teams Integration (v2.88)

Optimal Scenario: Integrated (Agent Teams + Custom Subagents)

This skill uses the INTEGRATED approach combining Agent Teams coordination with Custom Subagent specialization.

Why Scenario C for This Skill

• Iterative execution requires tight coordination between implementation and validation phases
• Quality gates (TeammateIdle, TaskCompleted) are essential for VERIFIED_DONE guarantee on each iteration
• Specialized ralph-coder agents for implementation, ralph-tester for validation
• Shared task list tracks iteration progress and blockers
• Multi-phase iteration (EXECUTE -> VALIDATE -> CHECK) benefits from team coordination

Configuration

1. TeamCreate: Create team "iterate-{task-hash}" on iterate invocation
2. TaskCreate: Create iteration tasks for each iterate cycle
3. Spawn: Use ralph-coder for implementation, ralph-tester for validation
4. Hooks: TeammateIdle + TaskCompleted for quality validation on each iteration
5. Coordination: Shared task list at ~/.claude/tasks/{team}/

Workflow Pattern

TeamCreate(team_name, description)
  → TaskCreate(iteration_n, "Implement iteration {n}")
  → Task(subagent_type="ralph-coder", team_name) for implementation
  → Task(subagent_type="ralph-tester", team_name) for validation
  → TaskUpdate(status="completed") when iteration passes gates
  → Hooks validate quality before marking complete
  → VERIFIED_DONE when all iterations pass

Team Creation Pattern

When /iterate is invoked, it automatically creates a dedicated team for the iteration:

# Automatic team creation
TeamCreate(
  team_name: "iterate-{task-hash}",
  description: "Iterative execution: {task}"
)

# Spawn implementation teammate
Task(
  subagent_type: "ralph-coder",
  team_name: "iterate-{task-hash}"
)

# Spawn validation teammate
Task(
  subagent_type: "ralph-tester",
  team_name: "iterate-{task-hash}"
)

Iteration Execution Flow

Each iteration follows this pattern:

1. Phase 1: Implementation

   • Spawn ralph-coder teammate
   • Execute task implementation
   • Teammate reports progress via TaskUpdate

2. Phase 2: Validation

   • Spawn ralph-tester teammate
   • Run quality gates
   • Collect validation results

3. Phase 3: Hook Verification

   • TeammateIdle hook triggers quality checks
   • task-completed-quality-gate.sh validates before completion
   • Exit 2 from hook = keep working with feedback
   • Exit 0 = proceed to next phase

4. Phase 4: Decision

   • All gates pass → VERIFIED_DONE
   • Any gate fails → Iterate (max 15/30)

Hook Integration Points

Hook	Trigger	Purpose
teammate-idle-quality-gate.sh	TeammateIdle	Quality checks before idle
task-completed-quality-gate.sh	TaskCompleted	Final validation before completion
ralph-subagent-start.sh	SubagentStart	Load Ralph context into teammates
glm5-subagent-stop.sh	SubagentStop	Quality gates when teammate stops

Team Composition

When /iterate is invoked, it automatically spawns:

Role	Purpose	Count
Leader	Loop coordinator, iteration management	1
ralph-coder	Implementation specialist	1
ralph-tester	Quality validation specialist	1

Total: 3 agents working in parallel (1 leader + 2 teammates)

Task Coordination

# Leader creates iteration task
TaskCreate(
  subject: "Implement iteration {n}",
  description: "{task requirements}",
  activeForm: "Implementing iteration {n}"
)

# Assign to coder
TaskUpdate(
  taskId: "{id}",
  owner: "ralph-coder",
  status: "in_progress"
)

# Coder completes work
TaskUpdate(
  taskId: "{id}",
  status: "completed"
)

# Leader validates, then marks VERIFIED_DONE or iterates

VERIFIED_DONE Guarantee

The Agent Teams system ensures VERIFIED_DONE through:

1. TeammateIdle Hook: Validates work quality before any teammate goes idle
2. TaskCompleted Hook: Final validation gate before task completion
3. Exit 2 Feedback: Hooks return exit 2 to request fixes with specific feedback
4. Task Coordination: TaskUpdate system tracks progress and blockers

This creates a quality feedback loop that prevents completion until all standards are met.

Output Location

# Logs saved to ~/.ralph/logs/
ls ~/.ralph/logs/iterate-*.log

# View last iterate execution
tail -f ~/.ralph/logs/iterate-latest.log

Pattern Details

Loop Structure

iteration=0
max_iterations=15  # or 30 for GLM-5/MiniMax

while [[ $iteration -lt $max_iterations ]]; do
    # Step 1: EXECUTE
    implement_task

    # Step 2: VALIDATE
    run_quality_gates  # tsc, eslint, tests, semgrep

    # Step 3: CHECK
    if all_gates_passed; then
        echo "VERIFIED_DONE"
        exit 0
    fi

    # Step 4: ITERATE
    ((iteration++))
    analyze_failures
    apply_fixes
done

# Max iterations reached without VERIFIED_DONE
exit 1

Quality Gates Integration

Each iteration runs quality gates:

1. TypeScript: tsc --noEmit
2. ESLint: eslint .
3. Tests: npm test or pytest
4. Security: semgrep --config=auto
5. Custom: Project-specific gates

Stop Hook Integration

The loop integrates with the Stop hook:

# Initialize state
.claude/scripts/ralph-state.sh init "$SESSION_ID" iterate "$TASK"

# On VERIFIED_DONE
.claude/scripts/ralph-state.sh complete "$SESSION_ID" iterate

# On failure
.claude/scripts/ralph-state.sh fail "$SESSION_ID" iterate "$ERROR"

Anti-Patterns

• Never use infinite loops (always set max_iterations)
• Never skip quality gates (defeats the purpose)
• Never use for one-shot tasks (use direct execution)
• Never nest loops (causes exponential iterations)

Completion Criteria

VERIFIED_DONE requires ALL:

1. All quality gates passed
2. No TypeScript errors
3. No ESLint errors
4. Tests passing
5. Security scan clean (no P0/P1 findings)
6. Parallel execution used for independent work (Agent Teams for complexity >= 3)
7. At least 2 teammates spawned when task involves code + tests

Autoresearch Delegation (v2.95)

When /iterate detects a metric-based optimization task, it can delegate to /autoresearch for continuous autonomous experimentation instead of running its own quality-gate loop.

Detection Criteria

A task is a candidate for autoresearch delegation when it contains:

1. A measurable metric (bundle size, latency, accuracy, memory usage, score, etc.)
2. An eval command that produces a numeric result (npm run build, pytest --benchmark, time ./run.sh)

Delegation Pattern

User Request	/iterate Behavior	Delegation
"iterate on reducing bundle size"	Detects metric: bundle size	/autoresearch src/ "npm run build"
"iterate on improving test coverage"	Detects metric: coverage %	/autoresearch src/ "npm run test:coverage"
"iterate until tests pass"	No metric, binary pass/fail	Stays in /iterate (quality-gate loop)
"fix lint errors"	No metric, binary pass/fail	Stays in /iterate (quality-gate loop)
"optimize inference latency below 50ms"	Detects metric: latency	/autoresearch src/model/ "python bench.py"

How It Works

User: /iterate "reduce bundle size by 30%"

/iterate detects:
  - metric: "bundle size"
  - eval: inferred from package.json -> "npm run build"
  - target: src/

/iterate delegates:
  /autoresearch src/ "npm run build" --checkpoint=5

The delegation happens at the start of the loop, before the first iteration. If the task does not match the metric-detection heuristic, /iterate proceeds with its standard EXECUTE -> VALIDATE -> QUALITY CHECK cycle.

Clear Distinction

Aspect	/iterate	/autoresearch
Purpose	Fix until tests/gates pass	Optimize a metric continuously
Loop type	Quality-gate loop	Experiment loop
Termination	All gates pass (VERIFIED_DONE)	Budget exhausted or metric target reached
Rollback	Fix forward	Git reset on regression
Decision	Binary pass/fail	Delta comparison (improved/equal/worse)
Best for	"Make it correct"	"Make it better"

When NOT to Delegate

• Task has no measurable metric (pure correctness fix)
• Task is part of an /orchestrator pipeline (orchestrator manages flow)
• User explicitly requests /iterate behavior with --no-delegate flag

Related Skills

• /orchestrator - Full orchestration workflow
• /gates - Quality validation gates
• /autoresearch - Autonomous metric-driven experimentation
• /adversarial - Spec refinement
• /parallel - Parallel subagent execution
• /retrospective - Post-task analysis

Action Reporting (v2.93.0)

Esta skill genera reportes automáticos completos para trazabilidad:

Reporte Automático

Cuando esta skill completa, se genera automáticamente:

1. En la conversación de Claude: Resultados visibles
2. En el repositorio: docs/actions/iterate/{timestamp}.md
3. Metadatos JSON: .claude/metadata/actions/iterate/{timestamp}.json

Contenido del Reporte

Cada reporte incluye:

• ✅ Summary: Descripción de la tarea ejecutada
• ✅ Execution Details: Duración, iteraciones, archivos modificados
• ✅ Results: Errores encontrados, recomendaciones
• ✅ Next Steps: Próximas acciones sugeridas

Ver Reportes Anteriores

# Listar todos los reportes de esta skill
ls -lt docs/actions/iterate/

# Ver el reporte más reciente
cat $(ls -t docs/actions/iterate/*.md | head -1)

# Buscar reportes fallidos
grep -l "Status: FAILED" docs/actions/iterate/*.md

Generación Manual (Opcional)

source .claude/lib/action-report-lib.sh
start_action_report "iterate" "Task description"
# ... ejecución ...
complete_action_report "success" "Summary" "Recommendations"

Referencias del Sistema

• Action Reports System - Documentación completa

• action-report-lib.sh - Librería helper

• action-report-generator.sh - Generador

• Unified Architecture v2.88

• Skills/Commands Unification

• Claude Code Skills Documentation

Anti-Rationalization

See master table: docs/reference/anti-rationalization.md

Excuse	Rebuttal
"VERIFIED_DONE — all tests pass"	Did you run ALL tests or just the new ones?
"The error is unrelated to my change"	Prove it. Run the full test suite.
"3 iterations is enough"	Iteration count doesn't determine quality. Exit criteria do.
"The fix works locally"	Local works is not verified. Run exit criteria.
"I'm stuck, marking as done with notes"	Stuck means escalate, not declare victory.
"The loop has been running too long"	Time is not a quality metric. Results are.
"Minor regressions are acceptable"	No regressions. Fix them or document why they're acceptable.