Convergence detect

Skill momentmaker/kaijutsu/skills/core/convergence-detect

Write your dev workflow once. Run it on any LLM. Open agent skills + multi-model swarm + a local findings store that learns which models you can trust.

Install

npx -y skills add momentmaker/kaijutsu --skill convergence-detect

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

3 stars3 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Detect when an iterative loop has stopped producing new signal. Use when another skill (polish, session-retro, plan refinement) needs a stop condition that's smarter than "ran N rounds". Three signals — output shrinking, change rate slowing, content similarity rising — indicate it's time to stop.

SKILL.md

4.8 KB, as published. Nobody here has run it

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.

Round	Output tokens
N-2	1500
N-1	800
N	350

Decreasing → signal to stop.

2. Change rate slowing

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

Round	Items	New	Restated
N-2	12	12	0
N-1	8	5	3
N	6	1	5

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.