Skip to content
Skills Library
Programming · Analysis

debug-issue

/debug-issue

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

Repository
ai-toolkit ↗
Licence
MIT
Last repository change
23.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 23.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

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

Triggers from the description

isnis brokenkeeps failing— even if they havendebugt wait for the user to say; if theygetting an error
Original author 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

How it works

  1. When to Activate
  2. Step 1: Capture the Problem
  3. Step 2: Locate the Origin
  4. Step 3: Gather Supporting Context
  5. Step 4: Analyze with debug-assistant-agent
  6. Step 5: Apply and Validate
  7. Staying on Track
Original SKILL.md headings · 117 lines, 1,002 words
SKILL.md preview
---
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.

Versions

RepositoryScoreLicence
This page · Uniswap/ai-toolkit100MIT
major-technology/cli90MIT

Database snapshot: 13.11.2026 · package version 8f274d04bd6b (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100debug-detective
    Find the root cause of a bug, crash, error message or failing test, then fix it. Use when the user says "this is broken", "why does this fail", "I get this error", "the test is failing", "it worked yesterday", or pastes a stack trace.
  • 100debug
    Debug a bug or unexpected behavior systematically. Use when the user says "there's a bug", "this isn't working", "I'm getting an error", "help me debug", "why is this failing", "unexpected behavior", "test is failing", "something is broken", or describes behavior that doesn't…
  • 100systematic-debugging
    Use when encountering a bug, test failure, crash, or unexpected behavior. Enforces root-cause investigation before any fix attempt. NOT for writing new features. Trigger: bug, error, failing test, broken, unexpected, crash, regression.
  • 100systematic-debugging
    Use when encountering a bug, test failure, crash, or unexpected behavior. Enforces root-cause investigation before any fix attempt. NOT for writing new features. Trigger: bug, error, failing test, broken, unexpected, crash, regression.
  • 100systematic-debugging
    Use when something is broken — an error message, stack trace, failing test, crash, wrong output, "it doesn't work", build failure, or unexpected behavior. Finds the root cause with evidence before changing code, then saves the fix to memory.
  • 95debugging
    Use when debugging bugs, test failures, or unexpected behavior. Triggers: 'why isn't this working', 'this doesn't work', 'X is broken', 'something's wrong', 'getting an error', 'exception in', 'stopped working', 'regression', 'crash', 'hang', 'flaky test', 'intermittent…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.