# Debug

> Systematically diagnose and fix bugs, unexpected behavior, or failing tests. Use when something is broken and the cause is not immediately obvious.

- Skill: `s1lver091/debug` (Agent Skill)
- Install (CLI): `npx skillmds@latest add s1lver091/debug`
- Raw SKILL.md: https://api.skillmd.com/api/skills/s1lver091/debug/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: s1lver091 (https://skillmd.com/u/s1lver091)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/s1lver091/debug

---


# Debugging

Do not guess. Work systematically: reproduce, isolate, hypothesize, verify.

## Step 1: Reproduce

Before touching any code, confirm you can reproduce the problem.
- What is the exact input or sequence of actions that triggers it?
- Is it consistent or intermittent?
- Does it happen in all environments or only some?

If you cannot reproduce it, stop and ask for more information.

## Step 2: Read the error

If there is an error message or stack trace:
- Read the full trace, not just the first line
- Find the deepest frame in your own code (not library internals) — that is your starting point
- Check what values were in scope at that point

## Step 3: Isolate

Narrow down where the problem lives before reading more code.
- Add temporary logging or assertions to confirm assumptions about state
- Bisect: is the problem in the input, the transformation, or the output?
- Check: when did this last work? Use `git log` and `git blame` to find recent changes

## Step 4: Form a hypothesis

Write one sentence: "I believe X is happening because Y."
Do not skip this. It prevents you from randomly changing code and hoping it works.

## Step 5: Verify the hypothesis

Find the code that should implement the behavior you described.
- Read it carefully
- Check the actual values at runtime if possible
- Look for edge cases the author may have missed

If your hypothesis is wrong, return to step 3. Do not guess-and-check.

## Step 6: Fix

Make the smallest possible change that fixes the root cause.
- Do not refactor surrounding code while fixing a bug
- Do not fix multiple bugs in one change
- After fixing, re-read the change and ask: could this break anything else?

## Step 7: Verify the fix

- Confirm the original issue no longer reproduces
- Check that related behavior still works
- If a test was failing, confirm it now passes and no others broke

## Report format

**Root Cause**
One sentence: what was actually wrong.

**Fix**
What you changed and why that addresses the root cause.

**Files Changed**
- `path/to/file.ts:42` — what changed

**Regression Risk**
Any adjacent behavior that should be tested after this fix.