chenwei791129 Systematically debug a problem using a four-phase workflow.
This skill enforces debugging discipline. No guessing, no random changes, no "let me try this." Every step is deliberate and evidence-based.
Input: The argument after $spectra-debug describes the bug or unexpected behavior. Examples:
$spectra-debug the search returns duplicate results$spectra-debug crash on startup after upgrading$spectra-debug file watcher misses rename events
The Three-Attempt Rule
Maximum 3 fix attempts per hypothesis in Phase 4 (Fix). Phases 1-3 (Reproduce, Isolate, Root Cause) are investigation — they do not count toward this limit. If your third fix attempt fails:
- Stop fixing
- Document what you tried and why it failed
- Question your hypothesis — is the root cause what you think it is?
- Research alternatives or try a completely different angle
Do NOT keep trying variations of the same approach. That's a loop, not debugging.
Phase 1: Reproduce
Before anything else, make the bug happen reliably.
- Find the exact steps to trigger the bug
- Identify the expected vs actual behavior — be precise
- Determine if it's consistent — does it happen every time? Only on certain input?
- Simplify the reproduction — strip away everything that's not essential
If you can't reproduce it, you can't debug it. Gather more information before proceeding.
Phase 2: Isolate
Narrow down where the bug lives.
- Binary search the codebase — which module, which function, which line?
- Check inputs and outputs — at each boundary, is the data correct?
- Add targeted logging — not everywhere, just at decision points
- Use git bisect when the bug is a regression — find the exact commit that introduced it
Goal: pinpoint the exact location where behavior diverges from expectation.
Phase 3: Root Cause
Understand WHY it's broken, not just WHERE.
Ask these questions:
- What assumption is being violated?
- What changed that made this start failing?
- Is this a symptom of a deeper issue, or the actual problem?
- Are there other places with the same pattern that might also be affected?
Don't stop at the first explanation. Verify your hypothesis:
- Can you predict the bug's behavior based on your theory?
- Does your theory explain ALL the symptoms, not just some?
- Can you construct a test case that proves the root cause?
Phase 4: Fix
Now — and only now — fix the bug.
- Write a failing test that reproduces the bug. If
tdd: trueis set in.spectra.yaml, fetch TDD instructions viaspectra instructions --skill tddand follow the Red-Green-Refactor cycle - Make the minimum change to fix the root cause — not the symptoms
- Run the test — confirm it passes
- Run the full test suite — ensure no regressions
- Check related code — if this pattern exists elsewhere, fix those too
Rationalization Table
| What You're Thinking | What You Should Do |
|---|---|
| "I bet it's this, let me just change it" | Reproduce first. Verify your hypothesis |
| "Let me add some prints everywhere" | Add targeted logging at specific boundaries |
| "It works on my machine" | Find what's different in the failing environment |
| "Let me try reverting this change" | Use git bisect to find the actual cause |
| "The fix is obvious, I don't need a test" | The fix is wrong. Write the test |
| "Let me just restart the service" | That hides the bug. Find the root cause |
| "Maybe if I just clear the cache..." | Understand why the cache was wrong |
Guardrails
- Don't guess — Every change must be based on evidence
- Don't fix symptoms — Find and fix the root cause
- Don't skip the test — Phase 4 always starts with a failing test
- Don't power through — After 3 failed attempts, stop and reassess
- Do keep notes — Document what you tried, what you found, what you ruled out
- Do check broadly — A bug in one place often means the same bug exists elsewhere