Iterative Refinement — Getting to the Right Output

Core 6 min +25 XP

💡

THE ANALOGY

A sculptor and client relationship. Not one shot — rough shape first, feedback, refine, feedback, polish. Each iteration is faster because direction is clearer. The best Claude Code workflows plan for this.

⚠️ EXAM TRAP — The Wrong Answer People Choose

Expecting perfect output on the first attempt for complex tasks, then treating the need for iteration as a failure. Iteration is a planned workflow, not a sign that something went wrong.

KEY POINTS

1 Plan for 2-3 iterations for complex outputs — budget this into your workflow.

2 Concrete input/output examples in the initial prompt dramatically reduce iterations needed.

3 Review structure first, content second, style last — don't give style feedback on draft 1.

4 Specific feedback beats vague — include the exact correction you want.

5 If the same feedback doesn't land, the instruction needs to change — not just be repeated.

Iteration Planning

Draft 1 → Feedback on STRUCTURE
  Is the overall shape right? Are all sections present? Is the order correct?
  Don't comment on style, wording, or details yet.

Draft 2 → Feedback on CONTENT  
  Are the details accurate? Are edge cases covered? Are examples correct?
  Don't comment on formatting yet.

Draft 3 → Feedback on STYLE
  Does it match the team standard? Is formatting consistent?
  This is the polish pass.

Concrete Examples Reduce Iterations

# Without examples — typically 3+ iterations
Generate API documentation for the refund endpoint.

# With examples — typically 1 iteration
Generate documentation for POST /api/v2/refunds following this EXACT format:

---
## POST /api/v2/refunds

**Description**: One sentence, active voice, describes what this endpoint does.

**Authentication**: Bearer token required | None

**Request Body**:
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| order_id | string | ✓ | Format: ORD-XXXXXXXX |

**Response 200**:
\```json
{"refund_id": "REF-123456", "status": "processing", "estimated_date": "2024-12-01"}
\```

**Error Codes**: 400 (invalid input), 404 (order not found), 422 (ineligible)
---

Now document all endpoints in src/api/v2/refunds.py using this format.

Specific Feedback

# ❌ Vague
"The error handling documentation isn't right"

# ✅ Specific — tells Claude exactly what to fix
"Error response documentation is missing two required fields:
1. 'code' — machine-readable error identifier (e.g., VALIDATION_ERROR, REFUND_INELIGIBLE)
2. 'field' — which request field caused the error (if applicable)

Current format: {error: string, message: string}
Required format: {error: string, code: string, message: string, field: string|null}

Update all error response examples to include these two additional fields."

Key Takeaways

Plan 2-3 iterations — not a failure, a workflow
Concrete examples reduce iterations dramatically
Structure → Content → Style — in that order
Specific feedback with exact corrections needed
Change the instruction if feedback isn’t working — not just repeat it