| name | iteration |
| description | The iterate-and-refine protocol. Use whenever the user says "iterate", "refine", "iterate and refine", "v-next", sends a terse correction on an existing artifact, or when a cold-scorer defect list or skill-failure classification requires a revision pass on prior work. Governs how deltas are applied to existing artifacts without rebuilding or drifting from source intent. |
Iteration
Iteration = surgical delta on an existing artifact, anchored to current state. Never a rebuild, never a fresh interpretation of the original ask.
Protocol
- Anchor — read
$SIA_STATE_PATH (and the artifact itself). The delta target comes from: user's correction > cold-scorer defects > Blocked/Next Steps in STATE.md. Restate the delta in one line.
- Classify the delta — capability gap (add) · logic bug (rewrite the wrong part) · stale fact (correct + note what disconfirmed it) · scope change (confirm with user first). Category decides the move; never apply a capability fix to a logic bug.
- Apply surgically — smallest change that closes the delta. Preserve everything the user didn't flag. Terse or garbled corrections ("yeah but", one-line fragments) are course corrections — decode against context, state the decoded intent, proceed.
- Verify — re-run the artifact's own verification (syntax check, parse, test). Evidence, not self-report.
- Close — version bump, one ledger line (
type: iteration, trigger, delta, evidence), update STATE.md sections the delta touched (Completed/Verified/Key Decisions). If a stored assumption was disconfirmed, say so explicitly — corrections to Claude's own state are deliverables, not embarrassments.
Rules
- One iteration = one delta set. Batch the user's corrections from a single message; don't split across replies.
- Stale-fact corrections propagate: fix every artifact carrying the disconfirmed fact, not just the one under discussion.
- End every iteration with exactly one next action + done-condition.
Failure modes — do NOT use when
- No prior artifact exists — that's creation, run the full loop.
- The correction changes the Goal — that's a re-plan; update STATE.md Goal with the user first, then iterate.
- The user is exploring/brainstorming — iterating on an unfixed target thrashes; converge first.
