convergence-detect

Iterative loops (review-fix loops, plan-polish loops, retrospective extraction) have a natural endpoint: when each new pass mostly restates the previous one, you're done. This skill is a primitive for detecting that endpoint quantitatively, so loops don't stop too early (missed signal) or too late (wasted tokens).

When to invoke

• Another skill says "use convergence-detect to decide when to stop"
• You're running a multi-round refinement and want a principled stop
• The user asks "are we done iterating?"

The three signals

Track these across the last 3 rounds (minimum). All three must point the same way before declaring convergence.

1. Output size shrinking

Token count of the output decreases round-over-round. New rounds add fewer findings, suggestions, or words than the previous.

Decreasing → signal to stop.

2. Change rate slowing

Of the items in round N, how many are new vs. restated from a previous round?

New / total approaching 0 → signal to stop.

3. Content similarity rising

Compare round N output to round N-1 output. If they're saying mostly the same things in different words, you've converged.

Practical heuristic without an embedding model:

• Take each finding/item from round N
• Check if a substantively-equivalent item appears in round N-1
• If 80%+ of round N items have a match in round N-1, they're saying the same thing

Quantitative scoring

Don't eyeball — measure.

• Output tokens: count tokens (or characters as a proxy) per round. Track the ratio tokens(N) / tokens(N-1). Below 0.6 = strongly shrinking; below 0.8 = mildly shrinking.
• New-item ratio: of the items in round N, count how many are new vs. restated. Items whose normalized text matches an item from N-1 (case-insensitive, whitespace-collapsed, identifier-equivalent) count as restated. Below 0.2 = strongly slowing.
• Jaccard similarity to previous round: |intersect(N, N-1)| / |union(N, N-1)|. Above 0.7 = strongly similar.

Optional: when an embedding endpoint is available, replace string-jaccard with cosine similarity over embeddings. More robust to paraphrase.

Persistence

Optionally log round-by-round signals to .claude/convergence-log/<loop-id>.jsonl (one JSON record per round). Schema:

{
  "round": 3,
  "tokens": 350,
  "new_items": 1,
  "total_items": 6,
  "similarity_to_prev": 0.83,
  "verdict": "converged",
  "verdict_confidence": "high"
}

Useful for retroactive tuning ("we declared converged at round 3 but pass 4 still found 2 issues — calibrate harder next time").

Stop condition

Declare convergence when ALL three signals fire simultaneously:

• Output size is shrinking (this round < previous round)
• New-item ratio is below 20%
• 80%+ of items have an equivalent in the previous round

If only 1-2 signals fire, run another round.

Hard rules

• Need at least 3 rounds before checking convergence. Two rounds isn't enough data to spot a trend.
• Don't conflate "agreement" with "convergence". If two rounds both produce 0 findings, that might be convergence — or it might be that the agent gave up. Verify by checking: did the agent actually look this round, or did it short-circuit?
• Convergence is per-loop, not per-skill. A polish loop on a small change might converge in 2 rounds; a plan-polish loop on a large doc might need 6.

Output shape

## Convergence check (round N)

| Signal             | Round N-2 | Round N-1 | Round N | Direction |
|--------------------|-----------|-----------|---------|-----------|
| Output tokens      | 1500      | 800       | 350     | shrinking |
| New-item ratio     | 100%      | 63%       | 17%     | dropping  |
| Similarity to prev | n/a       | 50%       | 83%     | rising    |

Verdict: CONVERGED (high confidence — all three signals strong)
        | CONVERGED (low — only 1 of 3 signals strong, see notes)
        | NOT CONVERGED — output shrinking but similarity still 60%

Or:

Verdict: NOT CONVERGED — output is shrinking but similarity is still 60%. Run another round.

Provenance

The three-signal model is from Jeffrey Emanuel's "Agentic Coding Flywheel" under "convergence detection". kaijutsu adopts it so other skills can call it as a primitive instead of redefining the rules.