4.2 KiB
| name | description |
|---|---|
| systematic-debugging | Find the actual root cause before proposing any fix - investigate, analyze patterns across similar cases, form and test a hypothesis, then implement. Use at the first sign of ANY bug, test failure, crash, error message, flaky test, or behavior that does not match expectations, and especially when tempted to try a quick patch. Triggers: this is broken, it is failing, why does this not work, weird error, test is red, it worked yesterday, intermittent failure. |
Random fixes waste time and create new bugs. Quick patches mask underlying issues.
Core principle: ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
The Iron Law: NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST. If you haven't completed Phase 1, you cannot propose fixes.
Use this for ANY technical issue: test failures, production bugs, unexpected behavior, performance problems, build failures, integration issues. Use it ESPECIALLY under time pressure, when "just one quick fix" seems obvious, or after you've already tried multiple fixes.
Phase 1: Root Cause Investigation
- Read error messages carefully — full stack traces, line numbers, file paths, error codes. Don't skip past warnings.
- Reproduce consistently — can you trigger it reliably? If not reproducible, gather more data, don't guess.
- Check recent changes — git diff, recent commits, new dependencies, config/environment differences.
- Gather evidence in multi-component systems — before proposing fixes, add diagnostic instrumentation at each component boundary (log what enters/exits, verify env/config propagation, check state at each layer). Run once to see WHERE it breaks, then investigate that component.
- Trace data flow backward — 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 symptom.
Phase 2: Pattern Analysis
- Find working examples similar to what's broken in the same codebase.
- Compare against references — if implementing a pattern, read the reference implementation completely, don't skim.
- Identify every difference between working and broken, however small.
- Understand dependencies — what settings/config/environment/assumptions does this need?
Phase 3: Hypothesis and Testing
- Form a single hypothesis: "I think X is the root cause because Y." Write it down.
- Test minimally — smallest possible change, one variable at a time.
- Verify before continuing. Worked? → Phase 4. Didn't work? → new hypothesis, don't stack more fixes on top.
- If you don't understand something, say so explicitly and ask/research rather than guessing.
Phase 4: Implementation
- Create a failing test case reproducing the bug first (use test-driven-development skill).
- Implement a single fix addressing the root cause — one change, no bundled refactoring.
- Verify the fix — test passes, no other tests broken, issue actually resolved.
- If the fix doesn't work: STOP. Count attempts. If < 3, return to Phase 1 with new information. If ≥ 3 fixes failed, STOP and question the architecture — don't attempt fix #4 without discussing fundamentals with your human partner. This is not a failed hypothesis, it's likely a wrong architecture (each fix reveals a new problem elsewhere, or requires "massive refactoring").
Red Flags — STOP and return to Phase 1
"Quick fix for now, investigate later" / "Just try changing X and see" / "Add multiple changes, run tests" / "Skip the test, I'll manually verify" / "It's probably X" / "I don't fully understand but this might work" / proposing solutions before tracing data flow / "one more fix attempt" after 2+ tries / each fix revealing a new problem elsewhere.
When "No Root Cause" Is Actually True
If systematic investigation truly reveals the issue is environmental/timing-dependent/external: document what you investigated, implement appropriate handling (retry/timeout/error message), add monitoring for future investigation. But 95% of "no root cause" cases are incomplete investigation — don't reach for this early.
Related skills
Use test-driven-development for the failing test in Phase 4. Use verification-before-completion to confirm the fix worked before claiming success.