Convergence Monitoring
Know when to stop agent fix loops by watching shrinking diffs, pass rates, and ceiling signals instead of guessing iteration counts.
Overview
Convergence monitoring is an agent skill most often used in Ship (also Build, Operate) that detects whether agent iterations are stabilizing or hitting a ceiling so you know when to stop.
Install
npx skills add https://github.com/juliusbrussee/cavekit --skill convergence-monitoringWhat is this skill?
- Defines convergence as declining change volume per iteration with a visual diff-shrink mental model
- Covers ceiling detection and non-convergence diagnosis when iterations stall or oscillate
- Uses test pass rate and forward-progress tracking for large agent-driven projects
- Frames stopping criterion as inconsequential remaining diffs, not a mandatory zero-diff
- Answers when to stop iterating and when diminishing returns mean pause or change strategy
- Illustrates convergence with a four-iteration diff-shrink example from 300 to 10 lines changed
Adoption & trust: 16 installs on skills.sh; 1k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You are running endless agent iterations and cannot tell if you are converging on a shippable solution or just paying for diminishing returns.
Who is it for?
Solo builders doing multi-iteration agent fixes on tests, refactors, or large features who need a stop rule tied to stability and pass rates.
Skip if: One-shot codegen with no iteration loop, or tasks where success is a single manual review with no measurable change or test signal between passes.
When should I use this skill?
Trigger when you ask about convergence, whether the agent is converging, ceiling detection, when to stop iterating, or diminishing returns on iterative agent work.
What do I get? / Deliverables
You get explicit convergence and ceiling signals—shrinking meaningful diffs, pass-rate trends, and forward-progress checks—so you stop or pivot with confidence instead of arbitrary iteration limits.
- Convergence vs ceiling vs non-convergence diagnosis
- Forward-progress assessment for continuing or stopping iterations
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Ship is the canonical shelf because convergence monitoring is mainly about deciding when iterative agent work is stable enough to release or stop burning tokens on test-fix cycles. Testing subphase fits the skill’s emphasis on test pass rate as a convergence metric and iteration outcomes tied to verification, not greenfield coding.
Where it fits
Track whether each agent pass still rewrites core modules or only polishes edges before you merge a large feature.
Watch test pass rate and diff size between agent remediation runs to decide if one more iteration is worth the cost.
Stop review-fix cycles when remaining agent changes are cosmetic and behavioral diffs have plateaued.
Diagnose non-convergence when production bug fixes oscillate or reintroduce regressions across agent sessions.
How it compares
Use instead of fixed “N more tries” chat loops when you need evidence-based stop rules for agent iteration.
Common Questions / FAQ
Who is convergence monitoring for?
Indie and solo developers who delegate multi-step fixes to coding agents and need a practical way to tell convergence from spinning wheels before ship or the next operate cycle.
When should I use convergence monitoring?
During Ship testing when pass rates and diffs should shrink between agent passes; during Build when an agent is iterating on a feature across many files; and during Operate iterate when production fixes risk endless tweak loops—whenever you ask if the agent is converging or when
Is convergence monitoring safe to install?
It is procedural guidance only and does not grant extra permissions by itself; review the Security Audits panel on this Prism page before installing any skill from the repo.
SKILL.md
READMESKILL.md - Convergence Monitoring
# Convergence Monitoring Convergence monitoring answers the most important question in iterative AI development: **when should you stop iterating?** The answer is not a fixed number of iterations or a time limit -- it is convergence. Convergence means the agent's output is stabilizing; each iteration produces fewer and smaller changes than the last. **Core insight:** You don't need a zero-diff -- you need the remaining modifications to be inconsequential. --- ## 1. What Is Convergence? Convergence appears as a rapid, consistent decline in the volume of changes from one iteration to the next: ``` Iteration 1: ████████████████████████████████████████ 300 lines changed Iteration 2: ████████████████ 120 lines changed Iteration 3: ██████ 40 lines changed Iteration 4: ██ 10 lines changed (cosmetic only) ^--- Convergence reached: the diff shrinks each pass until only cosmetic changes remain ``` ### Convergence indicators | Signal | What It Means | |--------|---------------| | **Lines changed decreasing exponentially** | Each iteration makes roughly half the changes of the previous one | | **Changes become trivial** | Remaining changes are formatting, comments, imports -- not behavior | | **Tests stabilize** | Test count stops increasing; pass rate approaches 100% | | **No new files created** | The architecture has settled; only existing files are modified | | **Impl tracking updates shrink** | Implementation tracking changes are status updates, not new findings | | **Completion signal emitted** | Agent determines all exit criteria are met | ### What convergence looks like in git ```bash # Check lines changed per iteration git log --oneline --stat # Iteration 5: trivial changes abc1234 Iteration 5: formatting and comment fixes 3 files changed, 8 insertions(+), 6 deletions(-) # Iteration 4: minor adjustments def5678 Iteration 4: edge case handling 5 files changed, 22 insertions(+), 8 deletions(-) # Iteration 3: moderate changes ghi9012 Iteration 3: complete API integration 12 files changed, 85 insertions(+), 31 deletions(-) # Iteration 2: significant changes jkl3456 Iteration 2: implement core features 18 files changed, 156 insertions(+), 42 deletions(-) # Iteration 1: major initial work mno7890 Iteration 1: initial implementation 25 files changed, 312 insertions(+), 15 deletions(-) ``` --- ## 2. What Is a Ceiling? A ceiling is when the agent **cannot make further progress** due to external constraints. Like convergence, it produces small diffs -- but for fundamentally different reasons. ``` Convergence: Agent is DONE -> small diffs because work is complete Ceiling: Agent is STUCK -> small diffs because agent cannot proceed ``` ### Ceiling causes | Cause | Example | How to Detect | |-------|---------|---------------| | **Missing dependency** | API not available, library not installed | Agent logs errors about unavailable resources | | **Ambiguous spec** | Requirement can be interpreted multiple ways | Agent oscillates between implementations | | **Tooling limitation** | Build tool does not support needed feature | Agent tries workarounds that do not converge | | **External service** | Test requires network access, external API | Tests fail with connection/timeout errors | | **Context window exhaustion** | Codebase too large for one session | Agent loses track of earlier work | | **Permission boundary** | Agent cannot access needed fil