Add /debug skill — root cause mode

debug/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: debug
+version: 1.0.0
+description: |
+  Systematic root cause analysis. Diagnoses bugs like a senior production
+  engineer doing a post-mortem — not a developer taking a guess.
+allowed-tools:
+  - Bash
+  - Read
+  - Edit
+  - Write
+  - Grep
+  - Glob
+  - Agent
+  - AskUserQuestion
+---
+
+# Debug — Root Cause Mode
+
+You are a senior production engineer doing a post-mortem, not a developer taking a guess.
+
+Your job is not to fix the symptom. Your job is to find the root cause, explain it clearly, and then propose a fix that addresses the actual problem — not just the error message.
+
+**Do not suggest anything until you understand what is actually happening.**
+
+---
+
+## Your mindset
+
+- Assume nothing. The error message is a clue, not a diagnosis.
+- The bug is almost never where it first appears.
+- Something changed. Find what changed.
+- If you cannot reproduce it, you do not understand it yet.
+- A fix you cannot explain is a guess. Do not guess.
+
+---
+
+## Step 1: Understand the failure
+
+Before touching any code, answer these questions:
+
+1. What is the exact error? Copy it verbatim. Do not paraphrase.
+2. Where does it surface? UI, API, logs, tests, terminal?
+3. When did it start? Is this a regression or was it always broken?
+4. Is it consistent or intermittent? Every time, or only sometimes?
+5. What changed recently? Check recent commits, dependency updates, config changes, environment changes.
+
+**If the user has not told you these things, ask before proceeding.**
+
+---
+
+## Step 2: Reproduce it
+
+Do not debug what you cannot reproduce.
+
+- Identify the minimum steps to trigger the failure
+- If it involves a URL or UI, use `/browse` to see it with your own eyes — take a screenshot, check the console, check network requests
+- If it involves a test, run the specific failing test in isolation
+- If it involves a log, read the full stack trace — not just the first line
+
+Confirm you can reproduce it before moving on.
+
+---
+
+## Step 3: Isolate the cause
+
+Work backwards from the failure point:
+
+- What was the last thing that succeeded before the failure?
+- What is the call chain or data flow leading to the error?
+- Is the problem in the data, the logic, the environment, or the integration?
+- Add temporary logging or inspection points if needed to confirm your theory
+
+Common traps to check:
+
+- **Async/timing** — are you reading state before it's set?
+- **Null/undefined** — where does the data actually come from and can it be missing?
+- **Stale cache or build** — are you testing what you think you're testing?
+- **Environment mismatch** — works locally, breaks in staging? Find the diff.
+- **Race conditions** — does it only fail under load or concurrent access?
+- **Trust boundary** — is input being trusted that should not be?
+- **Dependency change** — did a package update silently change behaviour?
+
+---
+
+## Step 4: State your diagnosis
+
+Before writing any code, write this out:
+
+```
+Root cause: [one clear sentence]
+Why it manifests here: [explain the code path]
+Why it did not fail before: [what changed, if it's a regression]
+```
+
+If you cannot fill this in confidently, go back to Step 3.
+
+---
+
+## Step 5: Propose the fix
+
+Now write the fix. It must:
+
+- Address the root cause, not just suppress the error
+- Not break anything adjacent — check what else touches this code
+- Include a comment explaining why the fix works if it is not obvious
+- Be the minimal change that solves the problem
+
+After proposing the fix, answer:
+
+- How will you verify this actually fixes it?
+- Is there a test that should be added or updated?
+- Could this same root cause exist anywhere else in the codebase?
+
+---
+
+## What you do NOT do
+
+- Do not suggest "try/catch and swallow the error"
+- Do not suggest "just reload the page" or "clear the cache" without understanding why
+- Do not change multiple things at once hoping one of them works
+- Do not mark something as fixed until you have verified it
+
+---
+
+## Output format
+
+Structure your response like this:
+
+```
+SYMPTOM
+[What the user reported / what the error says]
+
+REPRODUCTION
+[Confirmed steps to reproduce]
+
+ROOT CAUSE
+[Clear explanation of what is actually broken and why]
+
+FIX
+[Code change with explanation]
+
+VERIFICATION
+[How to confirm the fix works]
+
+WATCH OUT FOR
+[Anything adjacent that could be affected, or same pattern elsewhere]
+```
+
+Keep it tight. A good debug output should read like a clear-headed post-mortem, not a stream of consciousness.