/skill-iterative-loop

name: skill-iterative-loop
description: "Run tasks in a loop until goals are met — use for iterative refinement, polling, or convergence"
disable-model-invocation: true

> **Host: Codex CLI** — This skill was designed for Claude Code and adapted for Codex. > Cross-reference commands use installed skill names in Codex rather than `/octo:*` slash commands. > Use the active Codex shell and subagent tools. Do not claim a provider, model, or host subagent is available until the current session exposes it. > For host tool equivalents, see `skills/blocks/codex-host-adapter.md`.

Iterative Loop Execution

Overview

Systematic iterative execution with clear goals, exit conditions, and progress tracking.

**Core principle:** Define goal → Set max iterations → Execute → Evaluate → Loop or complete.

When to Use

**Use this skill when user wants to:**

• Execute a task multiple times with refinements
• Loop until a condition is met
• Iteratively improve something (code, tests, performance)
• Retry operations with modifications
• Progressive enhancement in rounds

**Do NOT use for:**

• Single execution ("run tests once")
• Manual step-by-step work
• Infinite loops without bounds
• Simple retry logic (use skill-debug)

The Process

Phase 1: Loop Setup

Step 1: Understand the Intent

**Loop Intent:**

Goal: [what should be achieved]
Success criteria: [how do we know we're done]
Max iterations: [safety limit]
Per-iteration tasks: [what to do each loop]

Step 2: Clarify Parameters

Use AskUserQuestion if unclear:

• **Max iterations:** How many times maximum?
• **Success condition:** What indicates we can stop early?
• **Per-iteration actions:** What exactly to do each round?
• **Failure handling:** What if it never succeeds?

Step 3: Safety Checks

**Safety Validation:**

- [ ] Max iterations defined (no infinite loops)
- [ ] Success condition is measurable
- [ ] Each iteration makes progress
- [ ] Failure exit strategy exists
- [ ] User aware of potential duration

**Never proceed without max iterations defined.**

Phase 2: Loop Execution

Step 1: Initialize Loop

**Starting Iterative Loop**

Goal: [description]
Max iterations: [N]
Success criteria: [condition]


### Iteration 1 / [N]

Step 2: Execute Iteration

For each iteration:

**Iteration [current] / [max]**

**Actions:**
1. [Action 1]
   → [result/output]
2. [Action 2]
   → [result/output]
3. [Action 3]
   → [result/output]

**Evaluation:**
- Success criteria met? [Yes/No]
- Progress made? [Yes/No]
- Issues found: [list any issues]

**Status:** [Continue/Success/Need intervention]

Step 3: Progress Tracking

Use task plan tool to track iterations:

Iteration Progress:
✓ Iteration 1 - [what was done]
✓ Iteration 2 - [what was done]
⚙️ Iteration 3 - [in progress]
- Iteration 4 - [pending]
- Iteration 5 - [pending]

Phase 3: Exit Conditions

Exit Condition 1: Success

🎉 **Success! Loop complete.**

**Goal achieved:** [description]
**Iterations used:** [N] / [max]

**Final state:**
[description of what was achieved]

**Summary of iterations:**
1. Iteration 1: [what happened]
2. Iteration 2: [what happened]
...
N. Iteration N: [what happened] ✓ Success

Exit Condition 2: Max Iterations Reached

⚠️ **Max iterations reached without full success**

**Iterations completed:** [max]
**Goal:** [description]
**Current state:** [how close we got]

**Progress made:**
- [Improvement 1]
- [Improvement 2]
- [Improvement 3]

**Remaining issues:**
- [Issue 1]
- [Issue 2]

**Options:**
1. Accept current state (substantial progress made)
2. Continue with [N] more iterations
3. Change approach (current method may not work)

What would you like to do?

Exit Condition 3: No Progress Detected

🛑 **Stopping early: No progress detected**

**Iteration:** [N] / [max]
**Reason:** Last [M] iterations showed no improvement

**Analysis:**
This suggests the current approach may be fundamentally flawed.

**Recommendation:**
Rather than continue looping, let's:
1. Analyze why no progress is being made
2. Consider alternative approaches
3. Re-evaluate the goal or success criteria

Shall we pause and reassess?

Common Patterns

Pattern 1: Loop with Testing

User: "Loop around 5 times auditing, enhancing, testing, until it's done"

Implementation:

**Loop Goal:** Code passes all quality gates
**Max Iterations:** 5
**Per-iteration:**
1. Audit code for issues
2. Enhance/fix identified issues
3. Run tests
4. Check if all pass

**Success:** All tests pass + no issues found

Execute:
Iteration 1:
- Audit → Found 8 issues
- Fix → Fixed 8 issues
- Test → 2 tests still failing
- Continue

Iteration 2:
- Audit → Found 2 new issues from fixes
- Fix → Fixed 2 issues
- Test → All tests pass ✓
- Success! Stopping early (2/5 iterations used)

Pattern 2: Performance Optimization Loop

User: "Keep trying optimizations until we hit < 100ms response time"

Implementation:

**Loop Goal:** Response time < 100ms
**Max Iterations:** 10
**Per-iteration:**
1. Measure current performance
2. Identify bottleneck
3. Apply optimization
4. Re-measure

**Success:** Response time < 100ms

Execute:
Iteration 1: 450ms → Cache database queries → 280ms (Continue)
Iteration 2: 280ms → Add index to frequent query → 150ms (Continue)
Iteration 3: 150ms → Implement response compression → 85ms (Success!)

Pattern 3: Retry with Backoff

User: "Try deploying, retry up to 3 times if it fails"

Implementation:

**Loop Goal:** Successful deployment
**Max Iterations:** 3
**Per-iteration:**
1. Attempt deployment
2. Check status
3. If failed, wait before retry

**Success:** Deployment succeeds

Execute:
Iteration 1: Deploy → Failed (API timeout) → Wait 10s
Iteration 2: Deploy → Failed (API timeout) → Wait 20s
Iteration 3: Deploy → Success ✓

Pattern 4: Incremental Refinement

User: "Iter