Debug Issue

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:

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.