skill-iterative-loop

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: "Iterate 4 times improving the error messages based on user feedback"

Implementation:

**Loop Goal:** Error messages meet clarity standard
**Max Iterations:** 4
**Per-iteration:**
1. Review current error messages
2. Identify confusing ones
3. Rewrite for clarity
4. Evaluate against criteria

**Success:** All messages rated 8+/10 for clarity

Execute each iteration with progressive improvement

Integration with Other Skills

With skill-debug

Loop for debugging:
"Keep debugging until all tests pass, max 5 tries"

Each iteration:
- Use skill-debug to investigate failure
- Apply fix
- Re-run tests
- Evaluate

With skill-audit

Loop for comprehensive checking:
"Loop 3 times auditing different aspects"

Iteration 1: Audit security
Iteration 2: Audit performance
Iteration 3: Audit accessibility

With skill-tdd

Loop for TDD cycles:
"Do 5 red-green-refactor cycles"

Each iteration:
- Write failing test (red)
- Make it pass (green)
- Refactor (refactor)
- Evaluate and continue

Best Practices

1. Always Define Max Iterations

Good:

Loop max 5 times trying to fix the issue

Dangerous:

Keep trying until it works
(What if it never works? Infinite loop!)

2. Measurable Success Criteria

Good:

Success: All 15 tests pass AND code coverage > 80%

Poor:

Success: Code looks better
(Too subjective)

3. Make Progress Visible

**Progress Tracking:**

Iteration 1: 5/15 tests passing
Iteration 2: 10/15 tests passing
Iteration 3: 13/15 tests passing
Iteration 4: 15/15 tests passing ✓

4. Early Exit on Success

Don't continue looping if goal is achieved:

**Iteration 2/5:** All tests pass!

Stopping early - goal achieved.
No need to continue to iteration 3.

5. Detect Stalls

Iteration 4: 10/15 tests passing
Iteration 5: 10/15 tests passing
Iteration 6: 10/15 tests passing

⚠️ No progress in 3 iterations - stopping to reassess approach

Red Flags - Don't Do This

| Action | Why It's Dangerous | |--------|-------------------| | No max iterations | Could loop forever | | Vague success criteria | Don't know when to stop | | No pr