# Ab Iterative Refinement

> Runs review-fix-review cycles on a change until quality converges: a deslop pass, then per iteration an ab-review-swarm review, findings routed by tier, fixes through ab-resolve-in-parallel, tests, build and a commit, until the convergence mode is met (fast: no P1, deep: no P1 or P2, perfect: none) or max_iterations (default 3) runs out. Use when ab-ship-pipeline or ab-build-pipeline reaches review, or when the user wants code polished past a single review pass. Not for a trivial change (one ab-review-swarm pass) or findings that need an architecture change (re-plan).

- Skill: `ninety2ua/ab-iterative-refinement` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx get-skill add ninety2ua/ab-iterative-refinement`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ninety2ua/ab-iterative-refinement/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: Ninety2UA (https://skillmd.com/u/ninety2ua)
- Updated: 2026-11-21
- Page: https://skillmd.com/skills/ninety2ua/ab-iterative-refinement

---


# Iterative Refinement

This skill takes an implemented change through review→fix→review cycles and ends with a final report: converged under the chosen mode, or stopped with the findings that remain. One pass catches most issues, a second catches those the fixes introduced, a third confirms convergence; past that, returns diminish. Skip it for a trivial change (under three files, simple logic), where one ab-review-swarm pass is enough, or before anything is implemented.

**Working folder.** Blueprint working files live under `.agent-blueprint/` in the project root. Before the first write there, make sure `.agent-blueprint/.gitignore` exists and lists `run/`, `team/`, `review-runs/`, `cache/` and `.gitignore`, so run state and the ignore file itself stay out of commits while plans and notes stay tracked.

**Provenance record.** Before any other work, run this as written from the project root: `mkdir -p .agent-blueprint/run/provenance && date -u +'{"skill": "ab-iterative-refinement", "version": "4.2.1", "started_at": "%Y-%m-%dT%H:%M:%SZ", "helper_steps": []}' > .agent-blueprint/run/provenance/ab-iterative-refinement.json`. It replaces any older record, and the Working folder step above has already made sure of `.agent-blueprint/.gitignore`. Each Helper step adds `{step, path: helper|inline}` to `helper_steps`. The record tells a run, and the smoke test, which skill ran and how; it is not a security control.

## Configuration

`max_iterations` (default 3, range 1-10) and `convergence` (default `fast`) come from the caller or the user.

| Mode | Exit when | Continue when |
|------|-----------|---------------|
| `fast` | P1 = 0 | P1 > 0 |
| `deep` | P1 + P2 = 0 | P1 + P2 > 0 |
| `perfect` | P1 + P2 + P3 = 0 | Any findings remain |

Only P3s left in fast mode means converged: they are suggestions, not blockers. Which mode suits which change, how callers use the loop, and common rationalizations: `references/guidance.md`.

## Step 0: Initialize

Take the `scope` to review (a diff, a branch or specific files; ab-ship-pipeline passes the branch against main) and record the start with `references/reports.md` § Start.

**No-commit mode.** If the user says not to commit, `AGENT_BLUEPRINT_GIT_WRITABLE` is `0`, or `.git` is read-only, make no commits: leave changes in the working tree and add the intended message to `.agent-blueprint/run/commit-msg.md`. With `AGENT_BLUEPRINT_GIT_WRITABLE=0`, the ship runner commits after the session, so it is not for work the user wants uncommitted. Reviews use the working tree and untracked files against the merge base instead of a commit range.

Here each 2a review covers the working tree and untracked files against the merge base, which holds the earlier iterations' uncommitted fixes, and 2f records its message instead of committing.

Review and fix helpers started for this loop return the shape in `references/return-contract.md`.

## Step 0.5: Deslop pass

Before the first review, clean AI-generated text patterns out of every changed file per `references/deslop.md`, run the tests, and revert any single change that breaks one. Reviewers share these blind spots, so this cheap pass catches what they miss.

## Step 1: The loop

Run Step 2 per iteration up to `max_iterations`, leaving at 2b when converged or at a stop condition (`references/guidance.md` § Loop diagram).

## Step 2: Each iteration

### 2a. Review

Announce "Refinement iteration [i]/[max] — dispatching review swarm." Run the ab-review-swarm skill on the scope and collect its synthesized P1/P2/P3 counts.

**Declined findings stay declined.** Keep a running list of findings already settled in earlier iterations: the user's Skip or Defer, a present-tier choice already made, a fix reverted as deferred in 2e. Pass the list to each new review round, and drop a re-raised finding that matches one by `file` + title fingerprint unless the code at that location changed since. Dropped re-raises don't count toward convergence.

### 2b. Check convergence

If the counts meet the mode's exit condition, report with `references/reports.md` § Converged and go to Step 3.

### 2c. Route by remediation tier

**Present tier (decisions required):** strategic choices with several valid approaches; the user decides before this iteration goes on.

**Asking the user.** Ask with your question tool if you have one, offering at most three options; otherwise ask in plain text with a numbered list. In a headless or unattended run nobody will answer: take the default named below, say so in your output, and log it in the run state's decisions if there is a run state.

Options: the finding's approaches, at most three. Default when nobody answers: the more conservative one. Under ab-ship-pipeline, take it without asking and log it.

**safe_auto:** mechanical fixes (typos, missing imports, formatting); apply them without asking and log them. **gated_auto:** resolve in 2d. **advisory:** list in the progress report, unfixed; fixing them adds churn.

### 2d. Resolve gated findings

Fix independent findings (different files, no shared state) concurrently with the ab-resolve-in-parallel skill, dependent ones (same file or shared state) in sequence. Each fix addresses only its finding: unrelated changes, new patterns or refactors create new findings and stall convergence. Fix an uncited or possibly deprecated framework pattern with the ab-source-driven-development skill: the installed version's current docs, URL cited. An `UNVERIFIED:` marker left in shipped code is always a fix target.

### 2e. Verify

Run the full test suite and build. On a failure, find the cause with the ab-systematic-debugging skill, fix it and re-run until green; after two failed attempts, revert that fix and mark its finding deferred. A fix that breaks tests is never committed, since the next review would chase the regression.

### 2f. Commit

Commit this iteration's fixes as `fix: address review findings (iteration [i]/[max])`.

### 2g. Progress report

Report with `references/reports.md` § Iteration progress.

## Stop conditions

End the loop early and escalate (Step 3) when iteration N finds the same findings as N-1 with zero fixes applied (they need human input), when fixes oscillate (fixing A breaks B and fixing B breaks A: a design issue), or when a finding needs an architecture change (stop and re-plan).

## Step 3: Final report

Report with `references/reports.md` § Final report. Max iterations reached with P1 > 0 is a warning: critical issues remain, and the caller (this skill, when standalone) stops and escalates to the user with `references/reports.md` § Escalation, as after a stop condition.

**Asking the user.** Ask with your question tool if you have one, offering at most three options; otherwise ask in plain text with a numbered list. In a headless or unattended run nobody will answer: take the default named below, say so in your output, and log it in the run state's decisions if there is a run state.

Options: the escalation's A, B and C. Default when nobody answers: merge nothing and return the report to the caller.

