convergence-loop — Claude Code skill: verify until it converges

---
name: convergence-loop
description: >-
  A universal gate-reinforcement meta-skill that replaces the "single-pass = done" pattern with a converging loop of up to N rounds. Can be applied to any gate, checkpoint, or verification step. Only declares "truly passed" after FAIL→FIX→re-verify repeats until convergence (all items pass). Escalates to structural redesign if not converged within N rounds. Triggers on: "convergence-loop", "how many rounds do we need", "suspicious of single-pass", "not sure if it really passed", or equivalent phrasing.
user-invocable: true
allowed-tools: ["Read", "Write", "Bash", "Agent"]
model: sonnet
origin: contention-layer
contention-parents: [harvest-loop]
---

# convergence-loop — Universal Convergence Loop Gate Reinforcement

> A single pass declaration is hard to trust. A fix exposes new FAILs, and round 2 catches what round 1 missed. convergence-loop assigns a "truly passed" criterion to any gate.

## Triggers

- `/convergence-loop`
- "convergence-loop", "how many rounds do we need", "not sure if it really passed"
- "suspicious of single-pass", "run until it passes", "keep verifying until clean"
- "single pass isn't enough", "need another round", "the fix might have introduced new issues"
- Auto-proposed: when the same artifact receives a FAIL verdict 2+ times in the same session (observable: 2nd FAIL on identical scope)

---

## Origin

Extracted from a recurring "single-pass gate is hard to trust" pattern observed across multiple hub workflows. The canonical reference is:
- `harvest-loop` extract→attack→synthesize cycle: pattern extraction → attack → synthesis → the repeating structure must run until convergence

When the same structure recurs across gates, it is a skill.

## Applicable Targets

| Applicable Gate | Example |
|---|---|
| Skill diagnostic gate | harness-doctor + apex-review |
| Session harvest loop | harvest-loop extract→attack→synthesize cycle |
| External asset audit | steel-quench Wave 1~N |
| Domain-specific quality gate | Plug in any project-defined FAIL→FIX checkpoint |
| Any FAIL→FIX repeating structure | User-defined gate |

---

## Pipeline Structure

```
[Input] gate name + pass criteria + max rounds N (default 3)
    │
    ▼
Round 1
    │  Execute gate
    │  → All items pass: ✅ Round 1 passed → Round 2 (verification)
    │  → FAIL occurs: List FAIL items → Execute FIX → Round 2
    │
    ▼
Round N (N ≥ 2)
    │  Re-execute same gate (with FIX applied + search for new FAILs)
    │  → All items pass AND no FIX was applied in response to THIS round:
    │        ✅ Declare truly passed  ← the only terminating exit
    │  → All items pass BUT you fixed something this round (any severity):
    │        the fix is unverified → Round N+1
    │  → New FAIL: List → FIX → Round N+1
    │
    ▼
    │  → FAILs remain after N rounds: "Structural redesign required" → Escalate
    │  → Rounds clean but each keeps producing fixes: the fixes are manufacturing the
    │    findings → REDUCE THE DESIGN, then re-run (steel-quench §Convergence Criteria 4)
    │
    ▼ (if not converged within N rounds)
Escalation
    → Classify root cause: ambiguous criteria / FIX capability limit / gate design flaw
    → Output recommended action
```

**Core principle**: A fix exposing new FAILs is not a failure — it is a **signal that the gate is working correctly**. The deeper the round, the more fundamental the FAILs it uncovers.

---

## Execution Guidelines

### Setup (confirm before running)

```
Gate name:       [what checkpoint is this]
Pass criteria:   [specify pass condition — "all items ✅" or concrete criteria]
Max rounds:      [default 3; simple gates 2; complex gates up to 5]
FIX owner:       [auto-fixable / requires human / mixed]
Escalation:      [who to escalate to / how, if not converged within N rounds]
```

### Per-Round Execution Rules

**What must stay constant across rounds**:
- Pass criteria are immutable (no relaxing criteria per round)
- Cumulative tracking of FAIL items (verify that prior-round FAILs were fixed)
- New FAILs explicitly labeled (distinguish newly surfaced items from fix chain)

**What changes across rounds**:
- FIX-applied targets (revised TCs, skills, documents)
- FAIL list (should shrink; growth is also acceptable — it means items are surfacing)

### Convergence Judgment

```
Convergence = a round returns 0 new FAILs AND no FIX was applied in response to it
Conditions to declare truly passed:
  1. All items pass AND
  2. Nothing was changed in response to THIS round, at any severity
     (a FAIL you accept as residual is terminal; a FAIL you fix is not — the fix is unverified) AND
  3. At least 2 rounds executed (a single clean round is "provisionally passed" only)
     ← condition 3 is NOT redundant with 2 and was nearly lost when 2 replaced it: freezing answers
       "did the artifact change under the audit", min-2 answers "is one look enough". Independent
       questions, both still open. Done When and the pipeline diagram enforce min-2 as well.
NOT "0 new FAILs across 2 consecutive rounds": while every round ships fixes that can never fire,
so it reads as permanently not-converged and gets shipped past anyway. Stricter form for quench
waves: steel-quench §Convergence Criteria.
```

### Escalation Root Cause Classification

| Cause | Signal | Recommended Action |
|---|---|---|
| Ambiguous pass criteria | Same item judged differently each round | Restate criteria explicitly, then restart |
| FIX capability limit | FAILs detected but fix method unknown | Bring in expert or reduce scope |
| Gate design flaw | Same FAIL repeats after N rounds | Redesign the gate itself → meta-prompt-builder |

---

## Output Format

```
## convergence-loop Result

Gate: [gate name]
Max rounds: N | Actual convergence round: M

| Round | Verdict | FAIL Items | New FAILs | FIX Applied |
|:---:|:---:|---|:---:|:---:|
| 1 | FAIL/PASS | [item list] | — | Y/N |
| 2 | FAIL/PASS | [item list] | [new] | Y/N |
| 3 | PASS | none | none | — |

✅ Truly passed (converged at round M)
❌ Not converged within N rounds → Escalation: [root cause classification]
```

---

## Related Skills

| Situation | Related Skill |
|---|---|
| Applied to skill diagnostic gate | `harness-doctor` → convergence-loop wrapper |
| Applied to quench wave | `steel-quench` Wave 3+ — **stricter**: S/A grade + the no-repair clause. Defer to its §Convergence Criteria, do not re-derive |
| Applied to session harvest loop | `harvest-loop` extract→attack→synthesize cycle |
| When gate redesign is needed | `meta-prompt-builder` |

## Done When

Each condition declares its check class (mandatory-pass / measured / judged); every judged condition
names its adversarial pairing — no judge-only path.

```
Setup complete (gate name, pass criteria, max rounds confirmed)
  (mandatory-pass — all three named in writing BEFORE round 1; criteria written after seeing round-1
   output are post-hoc and do not satisfy this)
+ Minimum 2 rounds executed
  (measured: round count >= 2, read off the per-round table below)
+ Convergence declared (a round returns zero new failures AND you make no repairs in response to
  it, at any grade) or escalation triggered
  (measured: the round's new-failure count = 0 AND its repair count = 0 — two numbers, both recorded
   per round; a single-number reading is what let "0 new failures while still repairing" pass)
  ⚠️ NOT "2 consecutive rounds": while every round ships repairs that criterion can never fire, so
  it reads as permanently not-converged and gets shipped past. Adjudicated with measured evidence in
  `steel-quench` §Convergence Criteria (2026-08-02).
+ Escalation root cause classified when max rounds is hit without convergence
  (judged — adversarial pairing: `fh-commons:quench-challenger` argues that the loop stopped because
   the GATE is blind rather than because the artifact is clean; an unchallenged "converged" on a
   gate that never produced a FAIL is the failure mode this pairing exists to catch)
+ Per-round result table output
  (mandatory-pass — one row per executed round, each carrying its new-failure and repair counts;
   a missing row makes the two measured conditions above unreadable)
```

## External anchor (independent convergence)

arXiv:2606.27009 (*Semantic Early-Stopping for Iterative LLM Agent Loops*, 2026-06-25, verified
2026-06-27) externally validates this skill's core thesis — **stop on convergence, not a fixed
iteration cap** — measuring −38% tokens vs fixed caps when stopping is *judge-free* (consecutive draft
embeddings stop changing in meaning). **Sharpening, not blind validation**: the same paper finds
*quality-gated* stopping (a judge call each round) counterproductive due to judging cost, and that an
oracle picking the best round beats any stopping rule — so the harder problem is *which* round was
best, not *when* to stop. Implication for this skill's judge/checklist-gated rounds: per-round
verification cost is real; prefer a cheap convergence signal where one exists, and keep `max rounds N`
bounded.