#What it does

The /debug skill applies a structured debugging methodology to any bug report, error log, or unexpected behavior. Instead of guessing, it follows a disciplined reproduce-isolate-fix-verify loop that tracks hypotheses and eliminates them one by one. It reads stack traces, inspects state, traces data flow, and narrows down the root cause before touching any code.

#How to use

/debug Users are seeing a 500 error when submitting the checkout form

You can also pass an error message, stack trace, or link to a Sentry issue directly.

/debug TypeError: Cannot read properties of undefined (reading 'map') at OrderList.tsx:47

#Workflow

1. Reproduce -- Gather all available context: error messages, stack traces, logs, user reports. Identify the exact steps or conditions that trigger the bug
2. Hypothesize -- Form 2-3 likely root cause hypotheses based on the evidence. Rank them by probability
3. Isolate -- Trace the data flow from input to failure point. Read the relevant source code, check recent commits that touched the area, inspect type definitions and edge cases
4. Root Cause -- Identify the exact line and condition causing the failure. Explain why it fails and under what circumstances
5. Fix -- Write the minimal, targeted fix. Prefer fixing the root cause over adding defensive checks that mask the real problem
6. Verify -- Write or update a test that reproduces the original bug and confirms the fix. Run the existing test suite to ensure no regressions

#Example

> /debug Payment webhook returns 200 but order status never updates
 
## Hypothesis 1 (HIGH): Webhook payload signature validation is failing silently
Reading src/api/webhooks/stripe.ts...
Found: catch block on line 34 returns 200 even on validation failure.
 
## Root Cause
The Stripe webhook handler catches signature verification errors
but still returns HTTP 200 to prevent retries. The order update
inside the try block never executes, but Stripe thinks delivery
succeeded.
 
## Fix
- Return 400 on signature failure (Stripe will retry)
- Add structured logging for webhook failures
- Add test: "should return 400 when signature is invalid"

#When to use

• Production errors you cannot reproduce locally
• Intermittent failures that appear under specific conditions
• Errors with misleading stack traces or swallowed exceptions
• Any time you find yourself adding console.log statements randomly