Spectra debug

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:

1. Stop fixing
2. Document what you tried and why it failed
3. Question your hypothesis — is the root cause what you think it is?
4. 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.

1. Write a failing test that reproduces the bug. If tdd: true is set in .spectra.yaml, fetch TDD instructions via spectra instructions --skill tdd and follow the Red-Green-Refactor cycle
2. Make the minimum change to fix the root cause — not the symptoms
3. Run the test — confirm it passes
4. Run the full test suite — ensure no regressions
5. 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