iterative-refinement

name	iterative-refinement
version	0.2.10
category	code-quality
description	Execute iterative refinement workflows with validation loops until quality criteria are met. Use this skill when running test-fix cycles, code quality improvement, performance optimization, or any task requiring repeated action-validate-improve cycles — even if they just say "keep improving until it passes" or "iterate on this". Not for testing-strategy.
license	MIT

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, known issues, optimal configurations, or recent alternatives for your validation tools.

Research first when: unfamiliar tools, new tech stack, complex quality criteria, or high-stakes optimization.

Core Loop Pattern

Every iteration follows:

1. Execute action (fix, optimize, improve)
2. Validate result (test, measure, check)
3. Assess progress (compare to criteria)
4. 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:

1. Take action - Apply fixes or implement changes

2. Run validator - Execute tests, linters, or measurements

3. Record progress:

   Iteration N:
   - Action: [what was done]
   - Results: [metrics/outcomes]
   - Issues remaining: [count/description]
   - Decision: [Continue/Success/Stop]
   

4. 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:

1. Analyze why progress stopped
2. Try different approach
3. Consider manual intervention
4. 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% ✓

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

See Also

• test-runner — Execute tests and diagnose failures
• testing-strategy — Choose testing approaches

Rationalizations

Rationalization	Reality
"I'll just keep iterating until it works"	Unbounded loops waste compute; define clear stop criteria before starting.
"The metrics are close enough"	Close enough is not passing; vague criteria hide incomplete work.
"Manual validation is faster than writing a test"	Manual checks don't repeat; automated validators catch regressions in future iterations.

Red Flags

• Running more than 15 iterations without convergence or re-evaluation
• Skipping validator execution between iterations
• Losing context from previous iterations leading to repeated failed approaches