Debug Issue

---
name: debug-issue
description: >-
  Systematic debugging workflow for any code error, crash, test failure, or unexpected behavior. Use this
  skill whenever a user mentions an error, bug, exception, crash, test failure, or says something "isn't working",
  "is broken", "keeps failing", or "isn't behaving as expected" — even if they haven't used the word "debug".
  Also trigger when the user pastes a stack trace, error message, or unexpected output and asks why. Don't wait
  for the user to say "debug"; if they're describing a problem with running code, this skill applies. Trigger
  phrases include: "getting an error", "this crashes", "why is this failing", "help me fix this", "it broke",
  "not working", "exception thrown", "stack trace", "test is failing", "something is wrong with".
allowed-tools: >-
  Read, Glob, Grep, Edit, Write, Bash(git log:*), Bash(git diff:*), Bash(git blame:*), Bash(git status:*),
  Task(subagent_type:debug-assistant-agent)
model: opus
---

# 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

**Fix it yourself and skip this step** when Step 3's evidence already confirmed the hypothesis
and the fix is contained: a null guard, a typo, a wrong comparison operator, an obviously
missing await, a stale import. Handing a one-line fix to an agent costs a full context load to
tell you what you already know. Note in your summary that you diagnosed it directly.

Delegate when the cause is still genuinely open after Step 3, the failure spans components,
it reproduces only intermittently, or your first fix did not hold.

When you do delegate, 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 fix, then confirm it works. The fix is whichever Step 4 produced: your own, if you
diagnosed it directly, or the agent's recommendation, if you delegated.

1. Make the code changes (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.