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.
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
Minimum 2 passes — MUST never single-pass. First pass discovers, second
verifies. One-pass work is not a convergence loop.
T20 tally every pass — MUST record Confirmed / Corrected / Extended / New
for every pass. No pass without a tally.
User gate before convergence declaration — MUST present tally and
recommend converged/not-converged. User decides. (CLAUDE.md guardrail #2)
Save state after every pass — MUST persist to state file. Convergence
loops are long-running and WILL hit compaction.
Graduated convergence — per-claim, not all-or-nothing. Converged claims
graduate; unconverged continue to next pass.
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.
Custom: compose any behavior sequence. Callers can inject domain-specific
instructions into agent prompts via the prompt customization hook (see
REFERENCE.md Section 7).
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
Verified claims set — corrected claims replace originals, with evidence
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)
Check input — identify claims format, count claims
If >100 claims: MUST suggest decomposition before starting. Do not proceed.
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
Select preset or custom sequence — present presets, recommend one
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).
Select domain slicing — see REFERENCE.md for templates. Caller picks or
customizes.
Initialize state file —
.claude/state/convergence-loop-{topic}.state.json (see REFERENCE.md Section
6 for schema)
Required output format (see REFERENCE.md Section 1)
Prior pass tally and corrections (EXCEPT fresh-eyes: gets nothing)
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.
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
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
Summarize pass delta — what was corrected, extended, or discovered.
Present narrative before tally numbers.
Present tally to user — include pass progress: "Pass {N} of {max}
({behavior})". Recommend converged/not-converged with confidence score.
User gate — user approves continuation or declares convergence
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:
Surface both positions with evidence
Recommend resolution based on evidence quality
User decides — or delegates ("you decide" accepted)
| Claim | Last Status | Agent Positions | Recommended Action |
Programmatic Mode
Other skills reference this skill's workflow without invoking
/convergence-loop directly. To integrate:
Read this SKILL.md's Workflow section
Implement the Setup -> Loop -> Report sequence in your skill's relevant phase
Use the T20 tally format
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):