Iterative Refinement

Execute workflows iteratively with systematic validation, progress tracking, and intelligent termination.

When to Use

Use for tasks requiring iterative refinement:

• Test-fix-validate cycles: Fix failures → retest → repeat until passing

• Code quality improvement: Review → fix → review until standards met

• Performance optimization: Profile → optimize → measure until targets achieved

• Progressive enhancement: Iterative improvements until diminishing returns

Don't use for single-pass tasks, purely parallel work, or simple linear workflows.

Pre-Usage Research (Optional)

Before starting iterations, consider researching:

• Current best practices for your validation tools (search "[tool] best practices 2025")

• Known issues with your tech stack (search "[language] [tool] common issues")

• Optimal configuration for your validators (search "[tool] configuration production")

• Recent improvements or alternatives (search "[tool] vs alternatives 2025")

Benefits:

• Better validators from the start

• Avoid known issues

• Use current best practices

• Save iteration cycles

When to research first:

• Unfamiliar validation tools

• New tech stack

• Complex quality criteria

• High-stakes optimization

Core Loop Pattern

Every iteration follows:

• Execute action (fix, optimize, improve)

• Validate result (test, measure, check)

• Assess progress (compare to criteria)

• Decide (continue or stop)

Instructions

Step 1: Define Configuration

Establish before starting:

Success Criteria (specific and measurable):

• Criterion 1: [Example: "All 50 tests passing"]

• Criterion 2: [Example: "Zero linter warnings"]

• Criterion 3: [Example: "Response time < 100ms"]

Loop Limits:

• Max iterations: 5-15 (justify if >20)

• Min iterations: (optional)

Termination Mode:

• Fixed: Run exactly N iterations

• Criteria: Stop when success criteria met

• Convergence: Stop when improvements < threshold (e.g., <10% over 3 iterations)

• Hybrid: Combine multiple conditions

Step 2: Execute Iteration

For each iteration:

• Take action - Apply fixes or implement changes

• Run validator - Execute tests, linters, or measurements

• Record progress: Iteration N:

• Action: [what was done]

• Results: [metrics/outcomes]

• Issues remaining: [count/description]

• Decision: [Continue/Success/Stop]

• Assess termination:

• All criteria met? → SUCCESS

• Improvement < threshold? → CONVERGED

• Reached max iterations? → STOP

• Otherwise → CONTINUE

Step 3: Pass Context Between Iterations

Each iteration needs:

• Previous results

• Current metrics

• Remaining issues

• Progress trend

This prevents repeating failed approaches.

Step 4: Handle Stuck States

If no progress for 2-3 iterations:

• Analyze why progress stopped

• Try different approach

• Consider manual intervention

• Stop if truly stuck

Step 5: Report Results

Loop Summary:

• Iterations: N
• Termination: [Success/Converged/Max/Stuck]
• Initial state: [metrics]
• Final state: [metrics]
• Improvement: [percentage/delta]
• Remaining issues: [list if any]

Validation Best Practices

Make Validators Specific

Bad: "Check if code is better" Good: "Run linter and count warnings"

Bad: "See if it's faster" Good: "Run benchmark: average response time over 100 requests"

Use Automated Validation

Prefer scripts/tools over manual inspection:

• Test frameworks over reading test code

• Linters over manual code review

• Benchmarks over estimated performance

• Coverage tools over counting tests

Capture Concrete Metrics

Track measurable progress:

• Test pass rate: 42/50 → 48/50 → 50/50

• Warning count: 23 → 8 → 2 → 0

• Response time: 320ms → 180ms → 95ms → 48ms

• Code coverage: 65% → 78% → 85% → 92%

Examples

Example 1: Test Fixing

Task: Fix all failing tests

Configuration:

• Success: 100% tests passing

• Max iterations: 8

Execution:

I1: 42/50 → Fix 8 failures → Continue I2: 48/50 → Fix 2 failures → Continue I3: 50/50 → SUCCESS ✓

Example 2: Linter Cleanup

Task: Remove all linter warnings

Configuration:

• Success: 0 warnings

• Max iterations: 5

Execution:

I1: 15 warnings → Fix → 6 warnings I2: 6 warnings → Fix → 1 warning I3: 1 warning → Fix → 0 warnings ✓

Example 3: Performance Loop

Task: Optimize response time

Configuration:

• Success: <50ms OR converged

• Max iterations: 15

• Convergence: <10% over 3 iterations

Execution:

I1: 320ms → Optimize → 180ms (44%) I2: 180ms → Optimize → 95ms (47%) I3: 95ms → Optimize → 48ms (49%) SUCCESS (target met)

Example 4: Coverage Improvement

Task: Increase test coverage to 90%

Configuration:

• Success: Coverage ≥ 90%

• Max iterations: 12

Execution:

I1: 65% → Write tests → 72% I2: 72% → Write tests → 81% I3: 81% → Write tests → 88% I4: 88% → Write tests → 91% ✓

Language-Specific Tools

For validation tools and commands for your language:

• Python: See tools/python.md

• JavaScript/TypeScript: See tools/javascript.md

• Rust: See tools/rust.md

• Java: See tools/java.md

• Go: See tools/go.md

• C/C++: See tools/cpp.md

• Ruby: See tools/ruby.md

• PHP: See tools/php.md

• C#/.NET: See tools/dotnet.md

Advanced Usage

For complex workflows, convergence detection, and advanced patterns: See patterns.md

Best Practices

DO:

✓ Define clear, measurable success criteria ✓ Set reasonable max limits (5-15) ✓ Use automated validators ✓ Pass context between iterations ✓ Track concrete metrics ✓ Stop early when criteria met ✓ Detect convergence ✓ Document changes

DON'T:

✗ Use loops for single-pass tasks ✗ Set high limits (>20) without justification ✗ Skip validation between iterations ✗ Lose context between iterations ✗ Continue after success/convergence ✗ Ignore stuck signals ✗ Use vague criteria ✗ Miss early termination