[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6M9HHD9CMBXVHEJHYP2WNET":3,"skill-same:01M6M9HHD9CMBXVHEJHYP2WNET":67},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":38,"linkOnly":39,"markdownContent":40,"markdownBody":41,"frontMatter":42,"refName":43,"commitSha":44,"skillDirectory":45,"forksCount":46,"repositoryHtmlUrl":47,"repositoryHomepageUrl":48,"ownerHtmlUrl":49,"ownerBlogUrl":50,"ownerDescription":51,"updatedAt":52,"install":53,"resources":66},"01M6M9HHD9CMBXVHEJHYP2WNET","convergence-monitoring",null,"Detecting whether agent iterations are converging toward a stable solution or hitting a ceiling. Covers convergence signals, ceiling detection, non-convergence diagnosis, test pass rate as a convergence metric, and forward progress tracking for large projects. Trigger phrases: \"convergence\", \"is the agent converging\", \"ceiling detection\", \"when to stop iterating\", \"diminishing returns\"","hashgraph-online\u002Fawesome-codex-plugins","hashgraph-online","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F160371962?v=4","01M6CNB6NRJVNNGN14TR01Q6D3","HOL (Hashgraph Online)","01M6JT1HSKKG9V68KQAQGBA7XP",1575,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002FJuliusBrussee\u002Fblueprint\u002Fskills\u002Fconvergence-monitoring\u002FSKILL.md",[],[19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37],"monitoring","convergence monitoring","convergence","when","test","rate","metric","for","detecting","progress","diagnosis","trigger","as","signals","stop","tracking","returns","projects","detection","2026-11-10 10:12:30",false,"---\nname: convergence-monitoring\ndescription: >\n  Detecting whether agent iterations are converging toward a stable solution or hitting a ceiling.\n  Covers convergence signals, ceiling detection, non-convergence diagnosis, test pass rate as\n  a convergence metric, and forward progress tracking for large projects.\n  Trigger phrases: \"convergence\", \"is the agent converging\", \"ceiling detection\",\n  \"when to stop iterating\", \"diminishing returns\"\n---\n\n# Convergence Monitoring\n\nConvergence 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.\n\n**Core insight:** You don't need a zero-diff -- you need the remaining modifications to be inconsequential.\n\n---\n\n## 1. What Is Convergence?\n\nConvergence appears as a rapid, consistent decline in the volume of changes from one iteration to the next:\n\n```\nIteration 1:  ████████████████████████████████████████  300 lines changed\nIteration 2:  ████████████████                          120 lines changed\nIteration 3:  ██████                                     40 lines changed\nIteration 4:  ██                                         10 lines changed (cosmetic only)\n              ^--- Convergence reached: the diff shrinks each pass until only cosmetic changes remain\n```\n\n### Convergence indicators\n\n| Signal | What It Means |\n|--------|---------------|\n| **Lines changed decreasing exponentially** | Each iteration makes roughly half the changes of the previous one |\n| **Changes become trivial** | Remaining changes are formatting, comments, imports -- not behavior |\n| **Tests stabilize** | Test count stops increasing; pass rate approaches 100% |\n| **No new files created** | The architecture has settled; only existing files are modified |\n| **Impl tracking updates shrink** | Implementation tracking changes are status updates, not new findings |\n| **Completion signal emitted** | Agent determines all exit criteria are met |\n\n### What convergence looks like in git\n\n```bash\n# Check lines changed per iteration\ngit log --oneline --stat\n\n# Iteration 5: trivial changes\nabc1234 Iteration 5: formatting and comment fixes\n 3 files changed, 8 insertions(+), 6 deletions(-)\n\n# Iteration 4: minor adjustments\ndef5678 Iteration 4: edge case handling\n 5 files changed, 22 insertions(+), 8 deletions(-)\n\n# Iteration 3: moderate changes\nghi9012 Iteration 3: complete API integration\n 12 files changed, 85 insertions(+), 31 deletions(-)\n\n# Iteration 2: significant changes\njkl3456 Iteration 2: implement core features\n 18 files changed, 156 insertions(+), 42 deletions(-)\n\n# Iteration 1: major initial work\nmno7890 Iteration 1: initial implementation\n 25 files changed, 312 insertions(+), 15 deletions(-)\n```\n\n---\n\n## 2. What Is a Ceiling?\n\nA ceiling is when the agent **cannot make further progress** due to external constraints. Like convergence, it produces small diffs -- but for fundamentally different reasons.\n\n```\nConvergence:  Agent is DONE      -> small diffs because work is complete\nCeiling:      Agent is STUCK     -> small diffs because agent cannot proceed\n```\n\n### Ceiling causes\n\n| Cause | Example | How to Detect |\n|-------|---------|---------------|\n| **Missing dependency** | API not available, library not installed | Agent logs errors about unavailable resources |\n| **Ambiguous spec** | Requirement can be interpreted multiple ways | Agent oscillates between implementations |\n| **Tooling limitation** | Build tool does not support needed feature | Agent tries workarounds that do not converge |\n| **External service** | Test requires network access, external API | Tests fail with connection\u002Ftimeout errors |\n| **Context window exhaustion** | Codebase too large for one session | Agent loses track of earlier work |\n| **Permission boundary** | Agent cannot access needed files or systems | Repeated permission errors in logs |\n\n### How to tell them apart\n\n| Dimension | Convergence (work is finishing) | Ceiling (work is stuck) |\n|-----------|--------------------------------|-------------------------|\n| **Size of diffs** | Shrinking steadily toward zero | Staying small but not trending down |\n| **Nature of changes** | Cosmetic -- whitespace, comments, naming | Functional but going in circles |\n| **Test results** | Pass rate climbing toward full coverage | Pass rate plateaued below target |\n| **Agent stance** | Wrapping up, marking exit criteria done | Retrying the same strategies repeatedly |\n| **Tracking status** | Tasks moving to DONE | BLOCKED items piling up |\n| **Recommended action** | Declare done, move to next phase | Diagnose the obstacle, resolve it, then continue |\n\n### How to distinguish them\n\n```\nCheck 1: Are tests passing?\n  YES, and improving -> Convergence\n  NO, stuck at same failures -> Ceiling\n\nCheck 2: Is the agent trying new approaches?\n  NO, just polishing -> Convergence\n  YES, but they all fail similarly -> Ceiling\n\nCheck 3: Are there BLOCKED tasks in impl tracking?\n  NO -> Convergence\n  YES -> Ceiling (read the blockers)\n\nCheck 4: Is the agent producing meaningful error messages?\n  NO, just minor changes -> Convergence\n  YES, about dependencies\u002Ftools\u002Faccess -> Ceiling\n```\n\n---\n\n## 3. Non-Convergence Signals\n\nNon-convergence means the agent is making changes, but they are NOT decreasing. The system is not stabilizing.\n\n```\nNon-convergence:\nIteration 1:  ████████████████████████████████████████  250 lines changed\nIteration 2:  ██████████████████████████████████████    230 lines changed\nIteration 3:  ████████████████████████████████████████  260 lines changed\nIteration 4:  ██████████████████████████████████        220 lines changed\n              ^--- NOT converging: changes are flat\u002Foscillating\n```\n\n### Root causes of non-convergence\n\n| Root Cause | Symptom | Fix |\n|-----------|---------|-----|\n| **Fuzzy specs** | Agent interprets requirements differently each iteration | Make specs more precise; add concrete acceptance criteria |\n| **Weak validation** | Agent cannot verify correctness, so it keeps changing things | Add build\u002Ftest\u002Flint gates; strengthen acceptance criteria |\n| **Fighting sub-agents** | Multiple agents change the same code in conflicting ways | Add file ownership tables; dispatch subagents via the Agent tool |\n| **Contradictory requirements** | Spec A says X, spec B says not-X | Resolve contradictions in specs; add explicit priority\u002Fprecedence |\n| **Missing exit criteria** | Agent does not know when it is done | Add explicit exit criteria checklists and completion signals |\n| **Over-broad scope** | Too much work for one prompt\u002Fiteration | Split into smaller, focused prompts with clear boundaries |\n| **Unstable dependencies** | External library or API keeps changing | Pin dependencies; mock external services in tests |\n\n### The critical rule\n\n**When the loop isn't stabilizing, the problem is upstream -- fix the specifications, validation, or coordination rather than adding more passes.**\n\nRunning more iterations when the system is not converging wastes time and compute. Instead:\n1. Stop the iteration loop\n2. Analyze the non-convergence pattern\n3. Fix the root cause (usually specs or validation)\n4. Resume the iteration loop\n\n---\n\n## 4. Test Pass Rate as Convergence Signal\n\nTest pass rate is the most reliable quantitative convergence signal. Track these metrics:\n\n### Metrics to monitor\n\n```\n| Iteration | Tests | Pass | Fail | Skip | Pass Rate | Delta |\n|-----------|-------|------|------|------|-----------|-------|\n| 1         | 45    | 30   | 15   | 0    | 66.7%     | --    |\n| 2         | 62    | 50   | 12   | 0    | 80.6%     | +13.9 |\n| 3         | 78    | 70   | 8    | 0    | 89.7%     | +9.1  |\n| 4         | 85    | 82   | 3    | 0    | 96.5%     | +6.8  |\n| 5         | 88    | 87   | 1    | 0    | 98.9%     | +2.4  |\n```\n\n### What to look for\n\n| Pattern | Meaning | Action |\n|---------|---------|--------|\n| **Test count increasing** | Agent is adding coverage | Good -- system is maturing |\n| **Pass rate approaching 100%** | Implementation matches specs | Good -- approaching convergence |\n| **Fewer failures per iteration** | Each pass fixes more than it breaks | Good -- healthy convergence |\n| **Pass rate plateaus \u003C 100%** | Some tests consistently fail | Ceiling -- investigate failing tests |\n| **Test count decreasing** | Agent is deleting tests | Bad -- investigate why; may be deleting inconvenient tests |\n| **Pass rate oscillating** | Fixes in one area break another | Non-convergence -- check for conflicting specs |\n\n### Automated convergence check\n\n```bash\n# After each iteration, check convergence signals\necho \"=== Convergence Check ===\"\n\n# 1. Lines changed (should be decreasing)\ngit diff --stat HEAD~1\n\n# 2. Test results (should be improving)\n{TEST_COMMAND} 2>&1 | tail -5\n\n# 3. Build health (should always pass)\n{BUILD_COMMAND} 2>&1 | tail -3\n\n# 4. Files changed (should be decreasing)\ngit diff --name-only HEAD~1 | wc -l\n```\n\n---\n\n## 5. Forward Progress Metrics\n\nFor large projects where full convergence takes many iterations, track forward progress toward eventual convergence.\n\n### Spec requirement coverage\n\nThe percentage of spec requirements with passing tests:\n\n```\nSpec Requirements Coverage:\n  spec-auth.md:     ██████████████████████████████████████  95% (19\u002F20 requirements)\n  spec-data.md:     ████████████████████████████████        80% (16\u002F20 requirements)\n  spec-ui.md:       ██████████████████████                  55% (11\u002F20 requirements)\n  spec-api.md:      ████████████████████████████            70% (14\u002F20 requirements)\n  ─────────────────────────────────────────────────────\n  Overall:          ████████████████████████████            75% (60\u002F80 requirements)\n```\n\n### Forward progress signals\n\n| Metric | Healthy Trend | Unhealthy Trend |\n|--------|--------------|-----------------|\n| **Requirements with passing tests** | Increasing each iteration | Flat or decreasing |\n| **Total test count** | Increasing | Flat or decreasing |\n| **DONE tasks in impl tracking** | Increasing | Flat with BLOCKED tasks growing |\n| **Open issues** | Decreasing | Increasing or flat |\n| **Dead ends documented** | Increasing slightly (learning) | Exploding (thrashing) |\n\n### Iteration velocity\n\nTrack how much progress each iteration makes:\n\n```\n| Iteration | Requirements Met | New This Iteration | Velocity |\n|-----------|-----------------|-------------------|----------|\n| 1         | 15\u002F80           | 15                | 15       |\n| 2         | 30\u002F80           | 15                | 15       |\n| 3         | 48\u002F80           | 18                | 18       |\n| 4         | 60\u002F80           | 12                | 12       |\n| 5         | 68\u002F80           | 8                 | 8        |\n| 6         | 73\u002F80           | 5                 | 5        |\n| 7         | 76\u002F80           | 3                 | 3        |\n```\n\nVelocity should decrease over time (easy requirements first, hard ones last), but should never hit zero. Zero velocity = ceiling.\n\n---\n\n## 6. When to Stop Iterating\n\n### Stop conditions (convergence reached)\n\nStop the iteration loop when ANY of these are true:\n\n1. **Completion signal emitted:** Agent outputs `\u003Call-tasks-complete>`\n2. **Changes are trivial:** Last iteration changed fewer than ~20 lines, all formatting\u002Fcomments\n3. **Test pass rate is stable:** Pass rate has been 95%+ for 2+ consecutive iterations\n4. **All exit criteria met:** Every `[ ]` in the exit criteria checklist is `[x]`\n5. **Forward progress stalled positively:** All spec requirements have passing tests\n\n### Continue conditions (not yet converged)\n\nContinue iterating when ALL of these are true:\n\n1. Changes are still substantial (behavior changes, not just formatting)\n2. Test pass rate is still improving\n3. There are still TODO or IN_PROGRESS tasks in impl tracking\n4. The iteration count is under the maximum\n\n### Investigate conditions (possible ceiling)\n\nPause and investigate when ANY of these are true:\n\n1. Changes are small but tests are NOT passing\n2. Agent is retrying the same approach repeatedly\n3. BLOCKED tasks are accumulating in impl tracking\n4. Test pass rate is oscillating (up-down-up-down)\n5. Agent is producing error messages about dependencies or tooling\n\n---\n\n## 7. Monitoring During Iteration Loops\n\n### What to monitor in real time\n\n```\n+------------------------------------------------------+\n| Convergence Dashboard                                |\n+------------------------------------------------------+\n| Iteration: 4\u002F10                                      |\n| Lines changed: 45 (prev: 112, trend: decreasing)    |\n| Files changed: 3 (prev: 8, trend: decreasing)       |\n| Test pass rate: 94.2% (prev: 87.1%, trend: up)      |\n| Tests: 82 total (prev: 75, trend: up)               |\n| BLOCKED tasks: 0 (prev: 1, trend: down)             |\n| Status: CONVERGING                                   |\n+------------------------------------------------------+\n```\n\n### Monitoring commands\n\n```bash\n# Quick convergence check after each iteration\necho \"--- Lines changed ---\"\ngit diff --stat HEAD~1 | tail -1\n\necho \"--- Files changed ---\"\ngit diff --name-only HEAD~1 | wc -l\n\necho \"--- Test results ---\"\n{TEST_COMMAND} --summary 2>&1 | tail -3\n\necho \"--- Impl tracking status ---\"\ngrep -c \"BLOCKED\\|IN_PROGRESS\\|TODO\\|DONE\" context\u002Fimpl\u002Fimpl-*.md\n```\n\n### Automated alerts\n\nSet up alerts for non-convergence signals:\n\n| Alert | Trigger | Action |\n|-------|---------|--------|\n| **Oscillation** | Lines changed increased vs previous iteration | Pause; check for conflicting changes |\n| **Stall** | Lines changed \u003C 5 but tests still failing | Pause; likely a ceiling |\n| **Regression** | Test pass rate decreased | Pause; investigate what broke |\n| **Runaway** | Lines changed > 500 for 3+ iterations | Pause; scope may be too broad |\n\n---\n\n## 8. Non-Convergence Recovery\n\nWhen you detect non-convergence, follow this recovery process:\n\n### Step 1: Stop the iteration loop\n\nDo not keep running. More iterations will not help.\n\n### Step 2: Diagnose the root cause\n\n```markdown\n## Non-Convergence Diagnosis\n\n### Symptoms\n- [ ] Changes are flat (not decreasing)\n- [ ] Changes are oscillating (up-down-up-down)\n- [ ] Agent is retrying failed approaches\n- [ ] Tests are oscillating (passing then failing)\n- [ ] Multiple agents changing the same files\n\n### Root Cause Analysis\n1. Check specs: Are requirements clear and unambiguous?\n2. Check validation: Can the agent verify correctness?\n3. Check file ownership: Are agents conflicting?\n4. Check scope: Is the prompt trying to do too much?\n5. Check dependencies: Are external resources available?\n```\n\n### Step 3: Fix the root cause\n\n| Root Cause | Fix |\n|-----------|-----|\n| Fuzzy specs | Rewrite ambiguous requirements with concrete acceptance criteria |\n| Weak validation | Add build\u002Ftest\u002Flint gates to the prompt |\n| File conflicts | Add file ownership tables; dispatch subagents via the Agent tool |\n| Over-broad scope | Split into smaller prompts; reduce concurrent agents |\n| External dependency | Mock the dependency; or resolve it before resuming |\n\n### Step 4: Resume the iteration loop\n\nAfter fixing the root cause, resume from where you stopped. Do NOT restart from scratch -- git history preserves all progress.\n\n```bash\n# Resume with the same prompt, possibly fewer remaining iterations\niteration-loop context\u002Fprompts\u002F003-generate-impl-from-plans.md -n 5 -t 1h\n```\n\n---\n\n## 9. Convergence and Revision\n\nRevision directly improves convergence by making specs more complete:\n\n```\nWithout revision:\n  Iteration 1: 200 lines, 5 manual fixes -> specs unchanged\n  Iteration 2: 180 lines, 4 manual fixes -> specs unchanged\n  Iteration 3: 170 lines, 4 manual fixes -> NOT converging\n\nWith revision:\n  Iteration 1: 200 lines, 5 manual fixes -> specs updated with 5 new requirements\n  Iteration 2: 100 lines, 2 manual fixes -> specs updated with 2 new requirements\n  Iteration 3: 50 lines, 0 manual fixes  -> CONVERGING\n```\n\n**Frequent manual fixes without revision = non-convergence.** The iteration loop keeps producing the same bugs because nothing in the specs prevents them.\n\n---\n\n## Cross-References\n\n- **Convergence patterns reference:** See `references\u002Fconvergence-patterns.md` for the complete convergence pattern catalog with examples.\n- **Revision:** See `ck:revision` skill for how tracing bugs to specs improves convergence.\n- **Prompt pipeline:** See `ck:prompt-pipeline` skill for designing prompts with proper exit criteria and completion signals.\n- **Validation-first design:** See `ck:validation-first` skill for building validation gates that provide convergence signals.\n- **Impl tracking:** See `ck:impl-tracking` skill for tracking progress and detecting ceiling conditions.\n","# Convergence Monitoring\n\nConvergence 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.\n\n**Core insight:** You don't need a zero-diff -- you need the remaining modifications to be inconsequential.\n\n---\n\n## 1. What Is Convergence?\n\nConvergence appears as a rapid, consistent decline in the volume of changes from one iteration to the next:\n\n```\nIteration 1:  ████████████████████████████████████████  300 lines changed\nIteration 2:  ████████████████                          120 lines changed\nIteration 3:  ██████                                     40 lines changed\nIteration 4:  ██                                         10 lines changed (cosmetic only)\n              ^--- Convergence reached: the diff shrinks each pass until only cosmetic changes remain\n```\n\n### Convergence indicators\n\n| Signal | What It Means |\n|--------|---------------|\n| **Lines changed decreasing exponentially** | Each iteration makes roughly half the changes of the previous one |\n| **Changes become trivial** | Remaining changes are formatting, comments, imports -- not behavior |\n| **Tests stabilize** | Test count stops increasing; pass rate approaches 100% |\n| **No new files created** | The architecture has settled; only existing files are modified |\n| **Impl tracking updates shrink** | Implementation tracking changes are status updates, not new findings |\n| **Completion signal emitted** | Agent determines all exit criteria are met |\n\n### What convergence looks like in git\n\n```bash\n# Check lines changed per iteration\ngit log --oneline --stat\n\n# Iteration 5: trivial changes\nabc1234 Iteration 5: formatting and comment fixes\n 3 files changed, 8 insertions(+), 6 deletions(-)\n\n# Iteration 4: minor adjustments\ndef5678 Iteration 4: edge case handling\n 5 files changed, 22 insertions(+), 8 deletions(-)\n\n# Iteration 3: moderate changes\nghi9012 Iteration 3: complete API integration\n 12 files changed, 85 insertions(+), 31 deletions(-)\n\n# Iteration 2: significant changes\njkl3456 Iteration 2: implement core features\n 18 files changed, 156 insertions(+), 42 deletions(-)\n\n# Iteration 1: major initial work\nmno7890 Iteration 1: initial implementation\n 25 files changed, 312 insertions(+), 15 deletions(-)\n```\n\n---\n\n## 2. What Is a Ceiling?\n\nA ceiling is when the agent **cannot make further progress** due to external constraints. Like convergence, it produces small diffs -- but for fundamentally different reasons.\n\n```\nConvergence:  Agent is DONE      -> small diffs because work is complete\nCeiling:      Agent is STUCK     -> small diffs because agent cannot proceed\n```\n\n### Ceiling causes\n\n| Cause | Example | How to Detect |\n|-------|---------|---------------|\n| **Missing dependency** | API not available, library not installed | Agent logs errors about unavailable resources |\n| **Ambiguous spec** | Requirement can be interpreted multiple ways | Agent oscillates between implementations |\n| **Tooling limitation** | Build tool does not support needed feature | Agent tries workarounds that do not converge |\n| **External service** | Test requires network access, external API | Tests fail with connection\u002Ftimeout errors |\n| **Context window exhaustion** | Codebase too large for one session | Agent loses track of earlier work |\n| **Permission boundary** | Agent cannot access needed files or systems | Repeated permission errors in logs |\n\n### How to tell them apart\n\n| Dimension | Convergence (work is finishing) | Ceiling (work is stuck) |\n|-----------|--------------------------------|-------------------------|\n| **Size of diffs** | Shrinking steadily toward zero | Staying small but not trending down |\n| **Nature of changes** | Cosmetic -- whitespace, comments, naming | Functional but going in circles |\n| **Test results** | Pass rate climbing toward full coverage | Pass rate plateaued below target |\n| **Agent stance** | Wrapping up, marking exit criteria done | Retrying the same strategies repeatedly |\n| **Tracking status** | Tasks moving to DONE | BLOCKED items piling up |\n| **Recommended action** | Declare done, move to next phase | Diagnose the obstacle, resolve it, then continue |\n\n### How to distinguish them\n\n```\nCheck 1: Are tests passing?\n  YES, and improving -> Convergence\n  NO, stuck at same failures -> Ceiling\n\nCheck 2: Is the agent trying new approaches?\n  NO, just polishing -> Convergence\n  YES, but they all fail similarly -> Ceiling\n\nCheck 3: Are there BLOCKED tasks in impl tracking?\n  NO -> Convergence\n  YES -> Ceiling (read the blockers)\n\nCheck 4: Is the agent producing meaningful error messages?\n  NO, just minor changes -> Convergence\n  YES, about dependencies\u002Ftools\u002Faccess -> Ceiling\n```\n\n---\n\n## 3. Non-Convergence Signals\n\nNon-convergence means the agent is making changes, but they are NOT decreasing. The system is not stabilizing.\n\n```\nNon-convergence:\nIteration 1:  ████████████████████████████████████████  250 lines changed\nIteration 2:  ██████████████████████████████████████    230 lines changed\nIteration 3:  ████████████████████████████████████████  260 lines changed\nIteration 4:  ██████████████████████████████████        220 lines changed\n              ^--- NOT converging: changes are flat\u002Foscillating\n```\n\n### Root causes of non-convergence\n\n| Root Cause | Symptom | Fix |\n|-----------|---------|-----|\n| **Fuzzy specs** | Agent interprets requirements differently each iteration | Make specs more precise; add concrete acceptance criteria |\n| **Weak validation** | Agent cannot verify correctness, so it keeps changing things | Add build\u002Ftest\u002Flint gates; strengthen acceptance criteria |\n| **Fighting sub-agents** | Multiple agents change the same code in conflicting ways | Add file ownership tables; dispatch subagents via the Agent tool |\n| **Contradictory requirements** | Spec A says X, spec B says not-X | Resolve contradictions in specs; add explicit priority\u002Fprecedence |\n| **Missing exit criteria** | Agent does not know when it is done | Add explicit exit criteria checklists and completion signals |\n| **Over-broad scope** | Too much work for one prompt\u002Fiteration | Split into smaller, focused prompts with clear boundaries |\n| **Unstable dependencies** | External library or API keeps changing | Pin dependencies; mock external services in tests |\n\n### The critical rule\n\n**When the loop isn't stabilizing, the problem is upstream -- fix the specifications, validation, or coordination rather than adding more passes.**\n\nRunning more iterations when the system is not converging wastes time and compute. Instead:\n1. Stop the iteration loop\n2. Analyze the non-convergence pattern\n3. Fix the root cause (usually specs or validation)\n4. Resume the iteration loop\n\n---\n\n## 4. Test Pass Rate as Convergence Signal\n\nTest pass rate is the most reliable quantitative convergence signal. Track these metrics:\n\n### Metrics to monitor\n\n```\n| Iteration | Tests | Pass | Fail | Skip | Pass Rate | Delta |\n|-----------|-------|------|------|------|-----------|-------|\n| 1         | 45    | 30   | 15   | 0    | 66.7%     | --    |\n| 2         | 62    | 50   | 12   | 0    | 80.6%     | +13.9 |\n| 3         | 78    | 70   | 8    | 0    | 89.7%     | +9.1  |\n| 4         | 85    | 82   | 3    | 0    | 96.5%     | +6.8  |\n| 5         | 88    | 87   | 1    | 0    | 98.9%     | +2.4  |\n```\n\n### What to look for\n\n| Pattern | Meaning | Action |\n|---------|---------|--------|\n| **Test count increasing** | Agent is adding coverage | Good -- system is maturing |\n| **Pass rate approaching 100%** | Implementation matches specs | Good -- approaching convergence |\n| **Fewer failures per iteration** | Each pass fixes more than it breaks | Good -- healthy convergence |\n| **Pass rate plateaus \u003C 100%** | Some tests consistently fail | Ceiling -- investigate failing tests |\n| **Test count decreasing** | Agent is deleting tests | Bad -- investigate why; may be deleting inconvenient tests |\n| **Pass rate oscillating** | Fixes in one area break another | Non-convergence -- check for conflicting specs |\n\n### Automated convergence check\n\n```bash\n# After each iteration, check convergence signals\necho \"=== Convergence Check ===\"\n\n# 1. Lines changed (should be decreasing)\ngit diff --stat HEAD~1\n\n# 2. Test results (should be improving)\n{TEST_COMMAND} 2>&1 | tail -5\n\n# 3. Build health (should always pass)\n{BUILD_COMMAND} 2>&1 | tail -3\n\n# 4. Files changed (should be decreasing)\ngit diff --name-only HEAD~1 | wc -l\n```\n\n---\n\n## 5. Forward Progress Metrics\n\nFor large projects where full convergence takes many iterations, track forward progress toward eventual convergence.\n\n### Spec requirement coverage\n\nThe percentage of spec requirements with passing tests:\n\n```\nSpec Requirements Coverage:\n  spec-auth.md:     ██████████████████████████████████████  95% (19\u002F20 requirements)\n  spec-data.md:     ████████████████████████████████        80% (16\u002F20 requirements)\n  spec-ui.md:       ██████████████████████                  55% (11\u002F20 requirements)\n  spec-api.md:      ████████████████████████████            70% (14\u002F20 requirements)\n  ─────────────────────────────────────────────────────\n  Overall:          ████████████████████████████            75% (60\u002F80 requirements)\n```\n\n### Forward progress signals\n\n| Metric | Healthy Trend | Unhealthy Trend |\n|--------|--------------|-----------------|\n| **Requirements with passing tests** | Increasing each iteration | Flat or decreasing |\n| **Total test count** | Increasing | Flat or decreasing |\n| **DONE tasks in impl tracking** | Increasing | Flat with BLOCKED tasks growing |\n| **Open issues** | Decreasing | Increasing or flat |\n| **Dead ends documented** | Increasing slightly (learning) | Exploding (thrashing) |\n\n### Iteration velocity\n\nTrack how much progress each iteration makes:\n\n```\n| Iteration | Requirements Met | New This Iteration | Velocity |\n|-----------|-----------------|-------------------|----------|\n| 1         | 15\u002F80           | 15                | 15       |\n| 2         | 30\u002F80           | 15                | 15       |\n| 3         | 48\u002F80           | 18                | 18       |\n| 4         | 60\u002F80           | 12                | 12       |\n| 5         | 68\u002F80           | 8                 | 8        |\n| 6         | 73\u002F80           | 5                 | 5        |\n| 7         | 76\u002F80           | 3                 | 3        |\n```\n\nVelocity should decrease over time (easy requirements first, hard ones last), but should never hit zero. Zero velocity = ceiling.\n\n---\n\n## 6. When to Stop Iterating\n\n### Stop conditions (convergence reached)\n\nStop the iteration loop when ANY of these are true:\n\n1. **Completion signal emitted:** Agent outputs `\u003Call-tasks-complete>`\n2. **Changes are trivial:** Last iteration changed fewer than ~20 lines, all formatting\u002Fcomments\n3. **Test pass rate is stable:** Pass rate has been 95%+ for 2+ consecutive iterations\n4. **All exit criteria met:** Every `[ ]` in the exit criteria checklist is `[x]`\n5. **Forward progress stalled positively:** All spec requirements have passing tests\n\n### Continue conditions (not yet converged)\n\nContinue iterating when ALL of these are true:\n\n1. Changes are still substantial (behavior changes, not just formatting)\n2. Test pass rate is still improving\n3. There are still TODO or IN_PROGRESS tasks in impl tracking\n4. The iteration count is under the maximum\n\n### Investigate conditions (possible ceiling)\n\nPause and investigate when ANY of these are true:\n\n1. Changes are small but tests are NOT passing\n2. Agent is retrying the same approach repeatedly\n3. BLOCKED tasks are accumulating in impl tracking\n4. Test pass rate is oscillating (up-down-up-down)\n5. Agent is producing error messages about dependencies or tooling\n\n---\n\n## 7. Monitoring During Iteration Loops\n\n### What to monitor in real time\n\n```\n+------------------------------------------------------+\n| Convergence Dashboard                                |\n+------------------------------------------------------+\n| Iteration: 4\u002F10                                      |\n| Lines changed: 45 (prev: 112, trend: decreasing)    |\n| Files changed: 3 (prev: 8, trend: decreasing)       |\n| Test pass rate: 94.2% (prev: 87.1%, trend: up)      |\n| Tests: 82 total (prev: 75, trend: up)               |\n| BLOCKED tasks: 0 (prev: 1, trend: down)             |\n| Status: CONVERGING                                   |\n+------------------------------------------------------+\n```\n\n### Monitoring commands\n\n```bash\n# Quick convergence check after each iteration\necho \"--- Lines changed ---\"\ngit diff --stat HEAD~1 | tail -1\n\necho \"--- Files changed ---\"\ngit diff --name-only HEAD~1 | wc -l\n\necho \"--- Test results ---\"\n{TEST_COMMAND} --summary 2>&1 | tail -3\n\necho \"--- Impl tracking status ---\"\ngrep -c \"BLOCKED\\|IN_PROGRESS\\|TODO\\|DONE\" context\u002Fimpl\u002Fimpl-*.md\n```\n\n### Automated alerts\n\nSet up alerts for non-convergence signals:\n\n| Alert | Trigger | Action |\n|-------|---------|--------|\n| **Oscillation** | Lines changed increased vs previous iteration | Pause; check for conflicting changes |\n| **Stall** | Lines changed \u003C 5 but tests still failing | Pause; likely a ceiling |\n| **Regression** | Test pass rate decreased | Pause; investigate what broke |\n| **Runaway** | Lines changed > 500 for 3+ iterations | Pause; scope may be too broad |\n\n---\n\n## 8. Non-Convergence Recovery\n\nWhen you detect non-convergence, follow this recovery process:\n\n### Step 1: Stop the iteration loop\n\nDo not keep running. More iterations will not help.\n\n### Step 2: Diagnose the root cause\n\n```markdown\n## Non-Convergence Diagnosis\n\n### Symptoms\n- [ ] Changes are flat (not decreasing)\n- [ ] Changes are oscillating (up-down-up-down)\n- [ ] Agent is retrying failed approaches\n- [ ] Tests are oscillating (passing then failing)\n- [ ] Multiple agents changing the same files\n\n### Root Cause Analysis\n1. Check specs: Are requirements clear and unambiguous?\n2. Check validation: Can the agent verify correctness?\n3. Check file ownership: Are agents conflicting?\n4. Check scope: Is the prompt trying to do too much?\n5. Check dependencies: Are external resources available?\n```\n\n### Step 3: Fix the root cause\n\n| Root Cause | Fix |\n|-----------|-----|\n| Fuzzy specs | Rewrite ambiguous requirements with concrete acceptance criteria |\n| Weak validation | Add build\u002Ftest\u002Flint gates to the prompt |\n| File conflicts | Add file ownership tables; dispatch subagents via the Agent tool |\n| Over-broad scope | Split into smaller prompts; reduce concurrent agents |\n| External dependency | Mock the dependency; or resolve it before resuming |\n\n### Step 4: Resume the iteration loop\n\nAfter fixing the root cause, resume from where you stopped. Do NOT restart from scratch -- git history preserves all progress.\n\n```bash\n# Resume with the same prompt, possibly fewer remaining iterations\niteration-loop context\u002Fprompts\u002F003-generate-impl-from-plans.md -n 5 -t 1h\n```\n\n---\n\n## 9. Convergence and Revision\n\nRevision directly improves convergence by making specs more complete:\n\n```\nWithout revision:\n  Iteration 1: 200 lines, 5 manual fixes -> specs unchanged\n  Iteration 2: 180 lines, 4 manual fixes -> specs unchanged\n  Iteration 3: 170 lines, 4 manual fixes -> NOT converging\n\nWith revision:\n  Iteration 1: 200 lines, 5 manual fixes -> specs updated with 5 new requirements\n  Iteration 2: 100 lines, 2 manual fixes -> specs updated with 2 new requirements\n  Iteration 3: 50 lines, 0 manual fixes  -> CONVERGING\n```\n\n**Frequent manual fixes without revision = non-convergence.** The iteration loop keeps producing the same bugs because nothing in the specs prevents them.\n\n---\n\n## Cross-References\n\n- **Convergence patterns reference:** See `references\u002Fconvergence-patterns.md` for the complete convergence pattern catalog with examples.\n- **Revision:** See `ck:revision` skill for how tracing bugs to specs improves convergence.\n- **Prompt pipeline:** See `ck:prompt-pipeline` skill for designing prompts with proper exit criteria and completion signals.\n- **Validation-first design:** See `ck:validation-first` skill for building validation gates that provide convergence signals.\n- **Impl tracking:** See `ck:impl-tracking` skill for tracking progress and detecting ceiling conditions.\n",{"name":5,"description":7},"main","2b63f856ce19c2a797929cacabd9e0fc936812fa","plugins\u002FJuliusBrussee\u002Fblueprint\u002Fskills\u002Fconvergence-monitoring",491,"https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins","https:\u002F\u002Fhol.org\u002Fplugins\u002Fbest-codex-plugins","https:\u002F\u002Fgithub.com\u002Fhashgraph-online","https:\u002F\u002Fhol.org","Open-source standards and developer tools for interoperable AI agents: discovery, identity, communication, payments, privacy and security.","2026-11-14 14:06:13",{"source":8,"skillName":5,"commands":54,"prompt":64,"zipAvailable":65},[55,58,61],{"tool":56,"command":57},"npx","npx skills add hashgraph-online\u002Fawesome-codex-plugins --skill convergence-monitoring",{"tool":59,"command":60},"bunx","bunx skills add hashgraph-online\u002Fawesome-codex-plugins --skill convergence-monitoring",{"tool":62,"command":63},"pnpm","pnpm dlx skills add hashgraph-online\u002Fawesome-codex-plugins --skill convergence-monitoring","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002FJuliusBrussee\u002Fblueprint\u002Fskills\u002Fconvergence-monitoring\u002FSKILL.md",true,[],[68,78,86,94,102,110],{"skillNo":69,"name":70,"nameZh":6,"description":71,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":72,"licenseFileUrl":73,"sourceHtmlUrl":74,"categories":75,"keywords":76,"publishedAt":77},"01M7DV332YQMGD8WTRJ9DZQXTB","worktable-review-with-annotations","Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.","MIT","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-review-with-annotations\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-review-with-annotations\u002FSKILL.md",[],[],"2026-11-15 14:19:17",{"skillNo":79,"name":80,"nameZh":6,"description":81,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":72,"licenseFileUrl":82,"sourceHtmlUrl":83,"categories":84,"keywords":85,"publishedAt":77},"01M7DV2YGHCZVBEB1AHYB6CGHE","worktable-find-and-synthesize-context","Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-find-and-synthesize-context\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-find-and-synthesize-context\u002FSKILL.md",[],[],{"skillNo":87,"name":88,"nameZh":6,"description":89,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":72,"licenseFileUrl":90,"sourceHtmlUrl":91,"categories":92,"keywords":93,"publishedAt":77},"01M7DV2TQN1H11ME2SAF9MXN7V","worktable-create-or-update-docs","Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-create-or-update-docs\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-create-or-update-docs\u002FSKILL.md",[],[],{"skillNo":95,"name":96,"nameZh":6,"description":97,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":72,"licenseFileUrl":98,"sourceHtmlUrl":99,"categories":100,"keywords":101,"publishedAt":77},"01M7DV2NE452NEA8TXATKSNAJH","worktable-create-or-manage-records","Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-create-or-manage-records\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-create-or-manage-records\u002FSKILL.md",[],[],{"skillNo":103,"name":104,"nameZh":6,"description":105,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":72,"licenseFileUrl":106,"sourceHtmlUrl":107,"categories":108,"keywords":109,"publishedAt":77},"01M7DV2HENRBR2KSCVM064WH0Y","worktable-create-or-manage-interactive-html","Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-create-or-manage-interactive-html\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-create-or-manage-interactive-html\u002FSKILL.md",[],[],{"skillNo":111,"name":112,"nameZh":6,"description":113,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":72,"licenseFileUrl":114,"sourceHtmlUrl":115,"categories":116,"keywords":117,"publishedAt":77},"01M7DV2CADR5R7RQFFYPNAGR9Y","worktable-collaborate-threads","Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-collaborate-threads\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-collaborate-threads\u002FSKILL.md",[],[]]