iterative-refinement

# Iterative-Refinement ## Overview Most agents, when told "this is okay but can be better," do one of two wrong things: 1. **Re-run the task from scratch.** Wastes budget, loses whatever was good in the first attempt, gambles on random variation. 2. **Polish by gut feel.** No loss signal, no gradient, no stopping criterion. Converges to the agent's aesthetic prior, not to a better deliverable. **Core principle:** refinement is a *second* gradient-descent pass, on the **y-axis** (the deliverable itself), using a **specific gradient** derived from the previous output's defects. The inputs, the task, the code, the skills — all held fixed. Only the deliverable changes. This is the skill-level equivalent of `awp refine` (AWP's normative refinement mode). See [`../../docs/ldd/convergence.md`](../../docs/ldd/convergence.md) §1 for the three-loop model. ## When to Use Invoke when **all** of: - A deliverable (document, code module, design artifact, plan) is **complete** (not partial, not stuck) - The deliverable is **usable but imperfect** — passes the minimum bar, fails the bar you actually want - Re-running the task from scratch would **lose** specific good parts of the current output - You can **name** the defects concretely (missing sections, weak examples, ambiguous language, missed requirements, incomplete coverage) Do **not** use when: - The deliverable is broken (use `loop-driven-engineering` + `root-cause-by-layer` — that's an inner-loop problem, not refinement) - Y...