[{"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",1559,"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",474,"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-11 14:40:14",{"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,76,83,90,116,141],{"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":15,"licenseFileUrl":6,"sourceHtmlUrl":72,"categories":73,"keywords":74,"publishedAt":75},"01M746ZWACVKMZ1BJXJZHYJSSX","migrate-to-e2e","Moves an existing Playwright, Cypress, Selenium, Appium, Detox, Maestro, or TesterArmy suite to e2e one slice at a time, with the old suite running beside the new one until each ported test is proven. Keeps a MIGRATION.md progress file so any later session resumes where the last stopped. Optionally plants a defect to show both suites catch it. Use for \u002Fmigrate-to-e2e, \"migrate our tests to e2e\", \"port these Maestro flows\", \"move our TesterArmy tests\", or when a project has an e2e config and an older suite still running.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Ftester-army\u002Fe2e\u002Fskills\u002Fmigrate-to-e2e\u002FSKILL.md",[],[],"2026-11-11 15:11:14",{"skillNo":77,"name":78,"nameZh":6,"description":79,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":80,"categories":81,"keywords":82,"publishedAt":75},"01M746ZPTAX1Q0FBKAB1CYND7E","e2e","Writes, runs, and debugs end-to-end tests for web and mobile apps with e2e, the agentic test runner, which mixes agent.act goals with exact locator assertions on a Playwright browser or an iOS or Android device. Also drives a project's running app live over the e2e MCP server to look at a screen, check a UI change, take a screenshot or record a video, and try a locator; and runs bug bashes, parallel e2e explore runs with each bug proven by a repro test. Use when a project depends on e2e or has an e2e.config.ts, when asked for end-to-end, browser, mobile, or agentic UI tests, to check a change in the running app, to QA or bug bash an app or branch, or when an e2e run fails.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Ftester-army\u002Fe2e\u002Fskills\u002Fe2e\u002FSKILL.md",[],[],{"skillNo":84,"name":85,"nameZh":6,"description":86,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":87,"categories":88,"keywords":89,"publishedAt":75},"01M746ZJN784HVHMDP9MQGCSGG","create-verification-skill","Generate a project-local verify-\u003Capp> skill on top of e2e, so any coding agent can launch the app, check it is worth driving, exercise a feature the way a user does, keep evidence, and bug bash it. Writes the skill, a feature map with one explore charter per feature, and proves it once. Use for \u002Fcreate-verification-skill, \"make a verification skill for this repo\", or when a project has no scripted way to prove UI behavior.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Ftester-army\u002Fe2e\u002Fskills\u002Fcreate-verification-skill\u002FSKILL.md",[],[],{"skillNo":91,"name":92,"nameZh":6,"description":93,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":94,"categories":95,"keywords":96,"publishedAt":38},"01M716A6ETNB9B1SQ3GXZC75VR","deja-search","deja-vu memory — search the user's past AI coding sessions with the deja CLI. Holds what they already settled and never wrote into the repo (naming rules, banned or already-tried tools, required checks before merge, preferred values, who owns what). Use before your first edit in a task, before you call a change done or ready to merge, before you recommend a tool, library, design or reviewer, before re-debugging an error that may already be solved, when they say 'didn't we fix this before', 'what did we decide about X' or 'I already have that', and before telling them something on this machine does not exist.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fvshulcz\u002Fdeja-vu\u002Fskills\u002Fdeja-search\u002FSKILL.md",[],[97,98,99,100,101,102,103,104,105,106,107,22,108,109,110,111,112,113,114,115],"search","deja search","never","error","ready","memory","re","decide","fix","design","debugging","you","done","reviewer","io","change","cli","merge","past",{"skillNo":117,"name":118,"nameZh":6,"description":119,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":120,"categories":121,"keywords":122,"publishedAt":38},"01M716A3J2W5SENSE9VGMXB375","deja-reflect","End-of-session reflection and memory curation with deja-vu. Review what was decided, what commands broke and what repaired them, and record durable project rules or decisions with deja remember so the next session starts with them.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fvshulcz\u002Fdeja-vu\u002Fskills\u002Fdeja-reflect\u002FSKILL.md",[],[123,124,125,111,126,127,128,129,130,131,132,133,134,135,102,136,137,138,139,140],"deja reflect","reflect","review","with","record","github","next","https","node","Rules","decisions","brew","remember","project rules","project","session","end","reflection",{"skillNo":142,"name":143,"nameZh":6,"description":144,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":145,"categories":146,"keywords":158,"publishedAt":38},"01M715T3RR4BAYSR57HPPTJ0PF","revid","Make, edit, export and post AI videos with Revid (revid.ai) through the Revid MCP server. Use whenever the user wants a short-form or long-form video made (from an idea, a script, a URL, an article, a PDF, a tweet, a product page, their own clips, or a song), wants to find what is going viral on TikTok, YouTube, Instagram or X before making something, wants to edit or re-export an existing Revid project, generate a standalone AI image or clip, make a series episode, or publish and schedule a finished video to connected social accounts. Covers setup (hosted MCP with OAuth, or an API key), the 36 tools, credits, polling and the rules for publishing. Routes to the more specific revid-* skills when one fits.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Ftmakersas\u002Frevid-skills\u002Fskills\u002Frevid\u002FSKILL.md",[147,152,155],{"categoryNo":148,"categoryName":149,"taxonomyType":150,"taxonomyTypeDesc":151},"01JBSEEDCAT000000000000016","图像与多媒体","SCENARIO","使用场景",{"categoryNo":153,"categoryName":154,"taxonomyType":150,"taxonomyTypeDesc":151},"01JBSEEDCAT000000000000023","Skill与智能体开发",{"categoryNo":156,"categoryName":157,"taxonomyType":150,"taxonomyTypeDesc":151},"01JBSEEDCAT000000000000010","后端与接口",[143,159,160,161,162,163,164,137,165,103,166,167,168,169,22,170,171,172,173,174],"URL","Video","short-form","standalone","PDF","viral","tiktok","short","social","MCP","song","image","mcp server","schedule","api","publish"]