Iterative Refinement Loop

The Core Idea

Don't expect perfection on the first pass. Plan for iterations from the start. Each pass has a different focus:

Pass 1: Structure — Get the shape right. Correct, complete, functional. Pass 2: Quality — Harden it. Edge cases, error handling, tests. Pass 3: Polish — Make it great. Performance, readability, documentation.

Why This Works

First-pass output from AI (or humans) has predictable weaknesses:

• Happy path works, edge cases don't
• Structure is right, details are wrong
• It works, but isn't maintainable
• The solution is correct but not elegant

Planning for iterations lets the first pass be fast and creative without pressure to be perfect. Subsequent passes are focused and surgical.

The Loop

┌─→ Build (fast, creative, get it working)
│     ↓
│   Critique (what's wrong? what's missing? what's fragile?)
│     ↓
│   Refine (fix the critique findings, improve)
│     ↓
│   Good enough? ──No──┘
│     │
│    Yes
│     ↓
│   Ship

Pass 1: Structure and Correctness

Goal: Get it working. All requirements met. No crashes.

Critique questions:

• Does it satisfy all requirements from the spec?
• Does the happy path work end-to-end?
• Is the overall architecture sound?
• Are there any structural problems that will be expensive to fix later?

Action: Fix structural issues only. Don't polish.

Pass 2: Quality and Robustness

Goal: Make it solid. Handle edge cases. Add tests.

Critique questions:

• What happens with null/empty/missing input?
• What happens with very large input?
• What happens when external services fail?
• Are errors handled gracefully?
• Is there test coverage for critical paths?
• Are there security vulnerabilities?

Action: Add error handling, edge cases, validation, tests.

Pass 3: Polish and Performance

Goal: Make it great. Optimize. Clean up.

Critique questions:

• Is the code readable to someone seeing it for the first time?
• Are there performance bottlenecks?
• Is there dead code or unnecessary complexity?
• Are names descriptive?
• Is the documentation up to date?
• Would you be proud to show this to a senior engineer?

Action: Optimize, refactor, document, clean up.

When to Stop

Stop iterating when:

• All acceptance criteria pass
• No CRITICAL or HIGH findings remain
• The next pass would produce diminishing returns
• Time box is reached

Don't stop because:

• "It works" (working is Pass 1, not done)
• You're tired of looking at it (that's when bugs hide)
• The deadline is tomorrow (cut scope, don't cut quality)

Applying to Different Domains

Code

• Pass 1: Working implementation, main test passes
• Pass 2: Edge case tests, error handling, security review
• Pass 3: Performance optimization, code cleanup, documentation

Writing

• Pass 1: Structure and content complete, all points covered
• Pass 2: Fact-check, logical flow, audience calibration
• Pass 3: Style, conciseness, formatting, proofreading

Architecture

• Pass 1: Components identified, data flow mapped, interfaces defined
• Pass 2: Failure modes, scalability, security analysis
• Pass 3: Cost optimization, operational concerns, documentation

Design

• Pass 1: Layout, information hierarchy, user flow
• Pass 2: Edge cases (empty states, errors, loading), accessibility
• Pass 3: Visual polish, micro-interactions, responsive behavior

Anti-Patterns

• Polishing on Pass 1 (wastes time if structure changes)
• Skipping critique (refinement without feedback is just rewriting)
• Too many passes (3 is usually enough; 5+ means the spec was wrong)
• Same critique every pass (each pass should find NEW issues, not repeat old ones)
• Refining without clear criteria for "done" (infinite loop)