Spectra Debug

---
name: spectra-debug
description: "Systematically debug a problem using a four-phase workflow"
effort: xhigh
license: MIT
compatibility: Requires spectra CLI.
metadata:
  author: spectra
  version: "1.0"
  generatedBy: "Spectra"
---
<!--
🔒 LOCKED — managed by clade
Source: plugins/hub-core/skills/spectra-debug/
Edit at: <clade-central-repo>
Local edits will be reverted by the next sync.
-->


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.

**Agent routing**: 若 debug 過程需派 codex 跑診斷 / repro，**MUST** 走 [`rules/core/agent-routing.codex-watch-protocol.md`](../../../../rules/core/agent-routing.codex-watch-protocol.md) § Codex 派工的標準流程 + Codex Watch Protocol；**禁止** `Agent` tool with `agent_type: screenshot-review` 派視覺 QA（per `rules/core/agent-routing.md` Routing Table — sonnet wrapper 已多次驗證 self-rationalize）。

**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

**clade fork — prod/staging runtime 症狀先查 evlog**：若 bug 來自 prod / staging（壞了、5xx、Toast error、「全部失敗」、變慢），第一個證據動作 MUST 是撈 evlog wide event（path / status / duration_ms / error_json / request.id / user / 時間窗）把症狀釘到具體 request，**先於** code grep / codebase-memory / 推測。code 是「可能發生什麼」，evlog 是「實際發生了什麼」。怎麼查見 `~/offline/clade/vendor/snippets/evlog-investigate/` 與 `rules/core/evlog-investigate.md`。

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 |
| "這是 prod bug，我先看 code 猜原因"        | 先撈 evlog wide event；prod root cause 在 evlog 驗證前都是推測 |
| "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