From convergence
Systematic root cause investigation. Use when encountering any bug, test failure, or unexpected behavior. Four phases: investigate, analyze patterns, hypothesize, fix. No fixes without root cause. If 3+ fixes fail, stop and question the architecture.
How this skill is triggered — by the user, by Claude, or both
Slash command
/convergence:debugThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Find the root cause before attempting fixes. Random fixes waste time and create new bugs.
Find the root cause before attempting fixes. Random fixes waste time and create new bugs.
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.
If you haven't completed Phase 1, you cannot propose fixes.
Use this ESPECIALLY when under time pressure. Systematic debugging is faster than guess-and-check thrashing.
Complete each phase before proceeding to the next.
Before investigating, dispatch the learnings-researcher agent with the error or symptom description. If a past learning matches, it may shortcut the investigation. Past learnings are hints, not answers — still verify against the current codebase.
Before attempting ANY fix:
Read error messages carefully. Don't skip past errors. Read stack traces completely. Note line numbers, file paths, error codes. The error message often contains the exact solution.
Reproduce consistently. Can you trigger it reliably? What are the exact steps? If not reproducible, gather more data — don't guess.
Check recent changes. git diff, recent commits, new dependencies, config changes, environmental differences.
In multi-component systems, add diagnostic logging at each boundary before fixing anything:
For EACH component boundary:
- Log what enters
- Log what exits
- Verify config propagation
Run once. The evidence shows WHERE it breaks.
Trace data flow. Where does the bad value originate? What called this with the bad value? Keep tracing up until you find the source. Fix at source, not at symptom.
Before proposing any fix, explain the full chain from trigger to symptom. Every link must be accounted for:
"A happens → which causes B → which causes C (the symptom we see)"
No gaps allowed. No "somehow A leads to C." If a link is uncertain, state a prediction: "If B is really the cause, then we should also see X." Test the prediction. If the prediction is wrong, the link is wrong — go back.
Create a failing test that reproduces the bug. Simplest possible reproduction.
Implement a single fix addressing the root cause. One change. No "while I'm here" improvements.
Verify. Test passes? Other tests still pass? Issue actually resolved?
If fix doesn't work:
/convergence-architectureDefense-in-depth check. After confirming the fix, grep for the same root cause pattern in other files. If found, flag: "Same pattern exists in [files]. Worth fixing there too?"
Compound nudge. If the root cause was non-obvious (required 3+ hypotheses or architectural escalation), suggest: "This was a non-trivial root cause. Consider running /convergence-compound to capture what was learned."
If you catch yourself thinking:
| Bad | Why | Do Instead |
|---|---|---|
| "Probably X, let me fix that" | Guessing, not investigating | Phase 1 first |
| Multiple fixes at once | Can't isolate what worked | One variable at a time |
| "Simple issue, skip the process" | Simple bugs have root causes too | Process is fast for simple bugs |
| Fix #4 without asking | 3 failures = architectural problem | Stop, question fundamentals with human |
| Fixing the symptom | Masks the real problem | Trace to source, fix there |
npx claudepluginhub c-sonnier/convergence --plugin convergenceEnforces systematic root cause investigation for bugs, test failures, and unexpected behavior through four phases: investigation, pattern analysis, hypothesis testing, and implementation.
Enforces systematic root cause analysis before fixes for bugs, test failures, unexpected behavior, performance issues, and build failures.
Enforces 4-phase root cause investigation for bugs, errors, test failures, unexpected behavior, and technical issues before proposing fixes.