| name | convergence-detector |
| description | Detects convergence issues in Ralph Wiggum Loop iterations: oscillation, stagnation, metric gaming, and context overflow. Use this skill when checking loop health or when the loop seems stuck.
|
Convergence Detector Skill
This skill analyzes Ralph Wiggum Loop state files to detect pathological loop behaviors.
When to Use
Run the convergence detector:
- After every N iterations (configured via
auto_review_interval)
- When the loop seems stuck
- When errors are repeating
- Before deciding whether to continue or stop the loop
Detection Modes
1. Oscillation Detection 🔄
What: Agent alternates between two states — fix A breaks B, fix B re-breaks A.
Check command:
bash .github/skills/convergence-detector/check-convergence.sh --mode oscillation
How it works:
- Examines the last N iteration entries in
PROGRESS.md
- Checks if the same files are being modified repeatedly
- Checks if error patterns alternate between two states
2. Stagnation Detection 🧊
What: Agent makes no meaningful progress across iterations.
Check command:
bash .github/skills/convergence-detector/check-convergence.sh --mode stagnation
How it works:
- Checks if any task has been
[~] for 3+ iterations
- Checks if
PROGRESS.md entries show "no changes"
- Compares task completion rate across recent iterations
3. Metric Gaming Detection 🎮
What: Agent manipulates success criteria instead of doing real work.
Check command:
bash .github/skills/convergence-detector/check-convergence.sh --mode gaming
How it works:
- Checks git diff for deleted test files
- Checks for weakened assertions (
.toBe → .toBeTruthy)
- Checks for added
@ts-ignore, eslint-disable, or any type casts
- Checks for deleted or commented-out test cases
4. Full Health Check
Check command:
bash .github/skills/convergence-detector/check-convergence.sh --mode all
Runs all detection modes and produces a combined health report.
Interpreting Results
| Exit Code | Meaning |
|---|
| 0 | Healthy — no issues detected |
| 1 | Warning — potential issues found |
| 2 | Critical — pathological behavior detected, stop recommended |
Integration
The convergence detector is automatically invoked by run-loop.sh when --auto-review
is enabled. You can also invoke it manually at any time to check loop health.
