convergence-loop

name	convergence-loop
description	Multi-pass verification of claims about reality using agent-based discovery, T20 tallies, and composable behaviors. Use when claims could waste effort if wrong — audits, discovery, doc-sync, plan verification.

Convergence Loop

Verify claims about reality through multi-pass agent loops with composable behaviors. Implements tenet T20 (research_convergence_loops) and T25 (discovery phases SHOULD use convergence loops).

Critical Rules

1. Minimum 2 passes — MUST never single-pass. First pass discovers, second verifies. One-pass work is not a convergence loop.
2. T20 tally every pass — MUST record Confirmed / Corrected / Extended / New for every pass. No pass without a tally.
3. User gate before convergence declaration — MUST present tally and recommend converged/not-converged. User decides. (CLAUDE.md guardrail #2)
4. Save state after every pass — MUST persist to state file. Convergence loops are long-running and WILL hit compaction.
5. Graduated convergence — per-claim, not all-or-nothing. Converged claims graduate; unconverged continue to next pass.
6. Contradictions are findings — disagreement between agents or sources is a discovery, not an error. Surface with evidence from both sides.

When to Use

• Verifying claims about codebase state (audit findings, diagnosis)
• Discovery phases in any skill (T25 — deep-plan, skill-audit, ecosystem audits)
• Validating plan completeness against requirements
• Cross-referencing documentation against code reality
• Any task where acting on wrong claims wastes significant effort

When NOT to Use

• Single-value lookups ("what version is X?")
• Mechanical operations (git mv, file deletion)
• Tasks with binary right/wrong answers verifiable by running code
• When claims set has <3 items (overhead exceeds value)

Composable Behaviors

Six behaviors that can be assigned to any pass. See REFERENCE.md Section 1 for full definitions, agent prompt templates, and required output format.

Behavior	Purpose	When to Use
source-check	Verify claims against source material	First pass (Loop 0)
discovery	Find NEW issues, not just confirm existing	Early passes
verification	Confirm/extend existing claims	Middle passes
fresh-eyes	Zero prior context — independent verify	Final pass
write-then-verify	Produce output then verify in same pass	Writing tasks
fix-and-re-verify	Apply corrections, re-verify without new pass	Mid-pass fixes

Presets

Preset	Sequence	Passes	Use Case
standard	source-check -> verification -> fresh-eyes	3	General purpose
quick	verification -> verification	2	Lightweight confirmation
thorough	source-check -> discovery -> verification -> verification -> fresh-eyes	5	High-stakes (SWS-level)
research-claims	verify-sources -> cross-reference -> temporal-check -> completeness-audit -> bias-check -> synthesis-fidelity	6	/deep-research claim verification

Custom: compose any behavior sequence. Callers can inject domain-specific instructions into agent prompts via the prompt customization hook (see REFERENCE.md Section 7).

---

Input

Auto-detected format — provide any of:

• Inline text: Claims listed in conversation
• File path: Document containing claims (e.g., DIAGNOSIS-v2.md)
• JSONL/JSON: Structured findings from audits or pipelines
• Conversation context: Claims from ongoing work

Valid claims: A claim is a testable assertion about codebase/documentation state. Each claim SHOULD have: (1) the assertion, (2) the source it references. Claims without sources default to source-check behavior scanning the full codebase.

MUST also provide or accept default for:

• Domain slicing strategy — how to split work across agents
• Preset or custom behavior sequence — which behaviors per pass

Output

1. Verified claims set — corrected claims replace originals, with evidence
2. Convergence report — summary table + claims delta (what changed and why)
3. Confidence score — HIGH (0 corrections in final 2 passes), MEDIUM (1 extension in final pass), LOW (corrections still declining but not zero)

For long-running or high-stakes loops, SHOULD write the convergence report to .claude/state/convergence-report-{topic}.md alongside the state file.

Quick Start Example

Topic: "Verify DIAGNOSIS-v2.md claims"
Input: /convergence-loop .planning/system-wide-standardization/DIAGNOSIS-v2.md
Preset: standard (source-check -> verification -> fresh-eyes)
Slicing: doc-by-section (4 agents)

Pass 1 (source-check): Confirmed 18, Corrected 3, Extended 2, New 1
Pass 2 (verification): Confirmed 22, Corrected 1, Extended 0, New 0
Pass 3 (fresh-eyes):   Confirmed 23, Corrected 0, Extended 0, New 0
-> CONVERGED (confidence: HIGH). 4 corrections applied, 2 extensions, 1 new.

Canonical first test: Run against DIAGNOSIS-v2.md (the document that motivated this skill's creation — per PLAN-v3.md Step 0.1 "done when").

---

Workflow

Validate (gate — before Setup)

1. Check input — identify claims format, count claims
   • If >100 claims: MUST suggest decomposition before starting. Do not proceed.
2. Check for existing state — if .claude/state/convergence-loop-{topic}.state.json exists, present: "Resuming convergence loop on {topic}. {N} passes complete. Last pass: {behavior}. Continue from pass {N+1}? [Y/restart]"

Setup

1. Select preset or custom sequence — present presets, recommend one
2. Configure agents — min 2, default 3-5, max 8. Scale to claims volume. Use the Agent tool with subagent_type appropriate to the domain (e.g., general-purpose for doc verification, code-reviewer for code claims).
3. Select domain slicing — see REFERENCE.md for templates. Caller picks or customizes.
4. Initialize state file — .claude/state/convergence-loop-{topic}.state.json (see REFERENCE.md Section 6 for schema)
5. Present warm-up — "Convergence loop: {topic}. Preset: {preset} ({N} passes). Agents: {N}. Slicing: {strategy}. Claims: {count}. Proceed? [Y/adjust]"

Loop (repeat per pass)

1. Dispatch agents — each agent gets:
   • Its domain slice of claims
   • Behavior instructions for this pass
   • Required output format (see REFERENCE.md Section 1)
   • Prior pass tally and corrections (EXCEPT fresh-eyes: gets nothing)
2. Collect results — gather all agent outputs
   • Agent output validation: If an agent returns <3 findings for a slice of

     10 claims, or returns findings without claim IDs, flag as degraded. Re-dispatch once. If second attempt fails, mark claims as "unverifiable."

   • Deduplication: If multiple agents report on the same claim, merge. If they agree, count once. If they disagree, route to Disagreement Handling.
3. Compute T20 tally:
   • Confirmed: claim verified as-is
   • Corrected: claim was wrong, replacement provided with evidence
   • Extended: claim was right but incomplete, additions provided
   • New: agent found something not in original claims
4. Graduated convergence check:
   • Claims with 2+ consecutive "Confirmed" across passes -> GRADUATED
   • Claims with "Corrected" or "Extended" -> continue to next pass
   • New findings -> added to claims set for next pass
5. Summarize pass delta — what was corrected, extended, or discovered. Present narrative before tally numbers.
6. Present tally to user — include pass progress: "Pass {N} of {max} ({behavior})". Recommend converged/not-converged with confidence score.
7. User gate — user approves continuation or declares convergence
8. Save state — full detail for current pass

Convergence Decision Logic

Recommend CONVERGED when:

• Zero corrections in latest pass AND
• Zero new findings in latest pass AND
• All remaining claims are Confirmed or Graduated

Recommend NOT CONVERGED when:

• Any corrections in latest pass, OR
• New findings discovered, OR
• Unresolved disagreements between agents

Warn at pass 3 without convergence trend: "3 passes without convergence — consider splitting the claims set or narrowing scope."

Hard cap: Default 5 passes. Configurable. After max: present partial results with unconverged claims flagged. Report MUST include an "Unconverged" section listing claims that never stabilized, with last known agent positions and recommended next action (decompose, manual review, or accept-as-is).

Disagreement Handling

When agents disagree on a claim:

1. Surface both positions with evidence
2. Recommend resolution based on evidence quality
3. User decides — or delegates ("you decide" accepted)
4. Record resolution rationale in state file

Report

Generate on convergence (or max passes):

Section 1 — Summary Table:

| Pass | Behavior      | Agents | Confirmed | Corrected | Extended | New |
|------|---------------|--------|-----------|-----------|----------|-----|
| 1    | source-check  | 4      | 18        | 3         | 2        | 1   |
| 2    | verification  | 3      | 22        | 1         | 0        | 0   |
| 3    | fresh-eyes    | 3      | 23        | 0         | 0        | 0   |
Confidence: HIGH | Convergence: ACHIEVED at Pass 3

Section 2 — Claims Delta (only changed claims):

| Claim | Original | Corrected/Extended | Evidence | Pass |

Section 3 — Unconverged (if max passes reached):

| Claim | Last Status | Agent Positions | Recommended Action |

---

Programmatic Mode

Other skills reference this skill's workflow without invoking /convergence-loop directly. To integrate:

1. Read this SKILL.md's Workflow section
2. Implement the Setup -> Loop -> Report sequence in your skill's relevant phase
3. Use the T20 tally format
4. Reference REFERENCE.md for behavior definitions and slicing templates

Caller return: For programmatic callers, return the verified claims set, convergence status, and confidence score. The calling skill resumes its workflow with the corrected claims.

Note: Integration with /deep-plan and /skill-creator complete (Session #222). Remaining callers (audit skills, /systematic-debugging) will integrate during Phase 3 ecosystem standardization.

Skills that MUST integrate (per T25 — discovery phases):

• /deep-plan — discovery phase
• /skill-audit — discovery phase
• /skill-creator — validation phase + planning prompt
• /create-audit — codebase exploration phase
• All audit skills — discovery phase
• /systematic-debugging — hypothesis generation

State Management

File: .claude/state/convergence-loop-{topic}.state.json Schema: See REFERENCE.md Section 6 for full JSON schema.

Graduated storage:

• Completed passes: tally summary + corrections list only
• Current pass: full agent outputs + intermediate results
• Always: input claims, behavior sequence, agent config, timestamps

Resume: Re-invoke /convergence-loop — Validate step detects existing state, presents status, offers continue/restart.

Guard Rails

• >100 claims: MUST suggest decomposition before starting (Validate gate)
• Pass 3 no trend: Warn, suggest scope split
• Agent timeout: Retry once, then mark claim "unverifiable", continue
• Agent degradation: <3 findings for >10 claims = re-dispatch once
• User "stop": Save state, present partial tally, offer resume/abandon
• Contradictory sources: Flag as finding (contradictions ARE findings)
• Scope explosion: If new findings exceed original claims count, pause and ask user whether to absorb or split
• Duplicate findings: Merge overlapping agent results before tallying

---

Version History

Version	Date	Description
1.1	2026-03-15	Skill-audit S1-S22: validation gate, warm-up, agent dispatch, output format, dedup, confidence score, resume detection, schema, quick-start example
1.0	2026-03-15	Initial creation via /skill-creator (Session #221, 17 discovery decisions)