/iterative-loop

name: "iterative-loop"
description: "Runs continuous AI iteration loops that repeat build-test-fix cycles until success criteria are met. Use when building features requiring test-driven refinement, implementing tasks with clear pass/fail criteria, or automating iterative improvement workflows."

Iterative Loop

Overview

The Iterative Loop skill implements **continuous AI-driven development loops** that persist until completion criteria are met. Inspired by the Ralph Wiggum technique, this approach enables autonomous, self-correcting development cycles where the AI sees its previous work in files and git history, iteratively improving until success.

Core Philosophy

1. **Iteration > Perfection** - Don't aim for perfect on first try; let the loop refine the work 2. **Failures Are Data** - Each failure provides information to improve the next attempt 3. **Clear Criteria** - Success must be objectively measurable (tests, metrics, validations) 4. **Persistence Wins** - Keep trying until success; the loop handles retry logic automatically

Prerequisites

• Claude Code with session management
• Clear completion criteria (tests, linting, metrics)
• Version control (git) for tracking iterations

---

Quick Start

Basic Iterative Development Pattern

# Define task with clear completion criteria
TASK="Implement user authentication with JWT.
Success criteria:
- All unit tests pass
- Integration tests pass
- No TypeScript errors
- Security audit passes
Output <promise>COMPLETE</promise> when all criteria met."

# Execute iterative loop (conceptual)
while ! task_complete; do
  claude_execute "$TASK"
  check_completion_criteria
done

AQE v3 Integration Example

# Using claude-flow hooks for iterative task
npx --no-install ruflo hooks pre-task --description "Implement auth with iteration" --taskId "auth-impl"

# Store iteration state in memory
npx --no-install ruflo memory store \
  --key "iteration-auth" \
  --value '{"iteration": 1, "maxIterations": 20, "criteria": "all tests pass"}' \
  --namespace iterations

---

Step-by-Step Guide

Step 1: Define Clear Success Criteria

**Essential**: Every iterative task MUST have objectively measurable completion criteria.

**Good Criteria Examples:**

✅ All unit tests pass (npm test returns exit code 0)
✅ Coverage > 80% (coverage report shows 80%+)
✅ No TypeScript errors (tsc --noEmit returns 0)
✅ Linting passes (eslint returns 0)
✅ Performance < 100ms (benchmark shows < 100ms)

**Bad Criteria Examples:**

❌ "Code looks good" (subjective)
❌ "Works properly" (undefined)
❌ "Well-structured" (no measurable check)

Step 2: Structure the Task with Phases

Break complex tasks into incremental phases:

## Task: Implement User Authentication

### Phase 1: Data Layer
- Create User model with Prisma schema
- Write migration
- Run tests: `npm test -- --grep "User model"`
- Criteria: Model tests pass

### Phase 2: Service Layer
- Implement AuthService with JWT
- Add token generation/validation
- Run tests: `npm test -- --grep "AuthService"`
- Criteria: Service tests pass

### Phase 3: API Layer
- Create /auth/login endpoint
- Create /auth/register endpoint
- Run tests: `npm test -- --grep "auth API"`
- Criteria: API tests pass

### Phase 4: Integration
- End-to-end authentication flow
- Run tests: `npm test`
- Criteria: ALL tests pass

Output <promise>AUTH_COMPLETE</promise> when Phase 4 passes.

Step 3: Implement Safety Mechanisms

Always include escape conditions:

## Safety Rules

1. **Max Iterations**: Stop after 20 attempts
2. **Stuck Detection**: After 5 iterations without progress:
   - Document what's blocking
   - List attempted approaches
   - Suggest alternative strategies
3. **Critical Errors**: Stop immediately if:
   - Database corruption detected
   - Security vulnerability introduced
   - Breaking changes to existing features

Step 4: Execute with Verification

Each iteration should: 1. Make targeted changes 2. Run verification (tests, lint, build) 3. Analyze results 4. Plan next iteration based on feedback

# Iteration pattern
1. Read previous state (files, git log)
2. Identify remaining work
3. Implement specific change
4. Run verification suite
5. If all pass -> output completion promise
6. If failures -> analyze and continue iteration

---

Iterative Patterns

Pattern 1: Test-Driven Iteration

## TDD Iteration Task

1. Write failing test for [feature]
2. Implement minimal code to pass test
3. Run `npm test`
4. If test fails -> debug and fix implementation
5. If test passes -> check if more tests needed
6. Repeat until all acceptance tests pass
7. Refactor if needed
8. Output <promise>TDD_COMPLETE</promise>

Pattern 2: Bug Fix Iteration

## Bug Fix Task

1. Write failing test that reproduces bug
2. Implement fix
3. Run test suite
4. If reproduction test fails -> analyze why fix didn't work
5. If other tests fail -> fix regressions
6. If all tests pass -> output <promise>BUG_FIXED</promise>

Max iterations: 10
After 5 iterations without fix:
- Document root cause analysis
- Suggest alternative approaches

Pattern 3: Coverage Improvement Iteration

## Coverage Improvement Task

Target: 80% line coverage

1. Run coverage analysis
2. Identify uncovered code paths
3. Write test for highest-impact uncovered path
4. Run tests with coverage
5. If coverage >= 80% -> output <promise>COVERAGE_ACHIEVED</promise>
6. If coverage < 80% -> continue iteration

Max iterations: 30
Progress check: If coverage doesn't improve for 3 iterations -> analyze blockers

Pattern 4: Performance Optimization Iteration

## Performance Optimization Task

Target: Response time < 100ms

1. Run performance benchmark
2. Identify slowest operation
3. Implement optimization
4. Run benchmark again
5. If target met -> output <promise>PERF_TARGET_MET</promise>
6. If not