debug-issue

What this skill does

# Debug Issue

Diagnose and fix any code problem — from vague symptoms to full stack traces — using a structured
investigation workflow backed by the `debug-assistant-agent`.

The skill accepts any form of bug report: a raw error message, a test failure output, a symptom
description ("the app freezes when I click save"), or a combination. Its job is to gather the right
context and translate that rough report into a root cause and a concrete fix.

## When to Activate

- User pastes an error message, exception, or stack trace
- A test is failing and the reason isn't obvious
- Something works locally but fails in CI or production
- Unexpected output that doesn't match what the code should do
- User says "this broke after my last change" — or doesn't know what changed

## Step 1: Capture the Problem

Before looking at any files, nail down what you're actually dealing with:

- **Symptoms** — what goes wrong? Extract the exact error type and message if there is one.
- **Trigger** — when does it fail? (always, sometimes, only after a specific action, only in prod)
- **Stack trace** — if present, read it carefully: the first project-owned frame (not a library frame)
  is the origin point and your starting location.

If the user gave vague symptoms only ("it just crashes"), ask one targeted clarifying question before
continuing — something like "do you have the error message or a stack trace?" But keep the interaction
short; once you have enough to locate the origin, move forward.

## Step 2: Locate the Origin

With the origin file and line in hand, read the code around the failure. The goal here is not to read
every related file — it's to form a working hypothesis fast.

- Read the relevant function or module: 10–20 lines around the error site give more useful context
  than the single failing line.
- Check whether this code changed recently (`git log -10 --oneline <file>` and `git diff HEAD~3 -- <file>`)
- Look for obvious candidates: null dereferences, incorrect assumptions about async ordering,
  missing env vars, changed interface contracts, off-by-one conditions.

Write your working hypothesis before moving to Step 3 — for example, "I believe this fails because
`userId` is undefined when `getUser()` is called on logout." A stated hypothesis keeps the
investigation from drifting into unfocused file-reading.

## Step 3: Gather Supporting Context

With a hypothesis in hand, collect the evidence that confirms or refutes it. Aim for depth over
breadth — three closely related files read carefully beat ten files skimmed.

Gather what the `debug-assistant-agent` needs:

| Piece                      | Where to find it                                                                         |
| -------------------------- | ---------------------------------------------------------------------------------------- |
| Full error and stack trace | User input, test output, or CI logs                                                      |
| Failing code               | Read the origin file; note surrounding functions if they're part of the call chain       |
| Recent changes             | `git log --oneline -5` on package.json, go.mod, requirements.txt, or the affected module |
| Config / env               | Check relevant .env files, config objects, or framework setup near the failure           |
| Logs                       | logs/ directory, stdout captures, or ask the user                                        |

If the evidence already strongly supports your hypothesis, you can delegate immediately. There's no
value in gathering everything available if you already understand the problem.

## Step 4: Analyze with debug-assistant-agent

Invoke the `debug-assistant-agent` with the structured context. Format your prompt to the agent as:

```
error: <exact error message and type, or "no explicit error — symptom: ...">
logs: <relevant log output, or "not available">
context: <the failing code and any related code you read — include file path and function name>
history: <recent git changes to this area, or "no recent changes">
environment: <runtime/framework/version info, or "standard dev environment">
```

The agent returns ranked root-cause hypotheses (with confidence scores), an error pattern
classification, a three-phase fix plan (immediate change → validation → deployment), and concrete
code patches.

Pick the highest-confidence hypothesis and fix plan. If two hypotheses are close in confidence,
note both and proceed with the more likely one — you can revisit if the first fix doesn't hold.

## Step 5: Apply and Validate

Apply the agent's recommended fix, then confirm it works:

1. Make the code changes the agent recommended (Edit/Write the affected files).
2. Run the relevant test or reproduce the original trigger.
3. If the error is gone, summarize for the user:
   - Root cause in plain language
   - What was changed and why it fixes the problem
   - Any follow-up to consider (adding a regression test, updating docs, monitoring a metric)
4. If the error persists or a different error appears, treat the new state as updated input and
   return to Step 2. What failed is useful information about where the real root cause lies.

## Staying on Track

Debugging can drift into exploration. Two guardrails that keep it productive:

- **One hypothesis at a time.** Pick the most likely cause, apply the fix, verify. Only move to
  the next hypothesis if verification fails. Trying to fix multiple hypotheses simultaneously
  muddies the signal.
- **Distinguish code bugs from environment issues.** If the root cause is a missing env variable,
  wrong Node/Python version, corrupted cache, or a service that's down — say so clearly. The fix
  is outside the code and applying a code patch won't help.