debugging

What it does and when to use it

A systematic method for finding the root cause of a bug, crash, error, or wrong output — reproduce, isolate, hypothesize, test, fix. Use when users report something broken, an exception/stack trace, flaky behavior, or 'why doesn't this work'. Triggers on mentions of bug, error, crash, stack trace, doesn't work, broken, exception, debug, root cause, 报错, 崩溃, 调试, 排查, 为什么不工作, 找原因.

Triggers from the description

How it works

1. Method
2. Fast checks before deep diving
3. Useful instrumentation
4. Guidance

---
name: debugging
description: "A systematic method for finding the root cause of a bug, crash, error, or wrong output — reproduce, isolate, hypothesize, test, fix. Use when users report something broken, an exception/stack trace, flaky behavior, or 'why doesn't this work'. Triggers on mentions of bug, error, crash, stack trace, doesn't work, broken, exception, debug, root cause, 报错, 崩溃, 调试, 排查, 为什么不工作, 找原因."
license: Proprietary. LICENSE.txt has complete terms
compatibility: "No external dependencies. Works on macOS, Linux, and Windows."
---

# Debugging

Don't guess-and-patch. Find the root cause first, then make the smallest fix.

## Method

1. **Reproduce reliably.** Get the exact steps, inputs, and environment that trigger it.
   A bug you can't reproduce, you can't confirm you've fixed.
2. **Read the actual error.** The stack trace usually names the file/line and the failing
   operation. Start there, not at your guess.
3. **Isolate.** Shrink the problem: comment out halves, hardcode inputs, binary-search the
   commit history (`git bisect`) or the code path until the failing piece is tiny.
4. **Form one hypothesis** about the cause, and make a prediction you can check ("if it's a
   null here, logging X will show None").
5. **Test the hypothesis** with a print/log/breakpoint or a minimal script — don't assume.
6. **Fix the cause, not the symptom.** Then re-run the reproduction to confirm it's gone,
   and check you didn't break a neighbor.
7. **Add a regression test** so it can't silently come back.

## Fast checks before deep diving

- Did it ever work? What changed (code, data, deps, env, time)? Check `git diff` / `git log`.
- Off-by-one, null/empty/zero, wrong type, wrong variable, stale cache, wrong env var.
- For "works on my machine": compare versions, paths, env vars, and locale/timezone.

## Useful instrumentation

```bash
# Narrow a flaky failure by running it many times
for i in $(seq 1 50); do <command> || { echo "failed on $i"; break; }; done
```

## Guidance

- State the root cause in one sentence before proposing the fix.
- If you can't reproduce it, say so and ask for the missing input/logs rather than guessing.
- Keep the fix minimal and explain why it addresses the cause.

Versions

Database snapshot: 13.11.2026 · package version 99243de15e35 (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
  Systematic root-cause debugging — reproduce, isolate, hypothesize, fix with TDD. Use when: bug, error, fix, broken, crash, exception, not working, unexpected behavior, 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.
• 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 records the fix in Engram memory.
• 100systematic-debugging
  Root-cause-first debugging methodology for any bug, test failure, exception, or unexpected behavior — mandates investigation before proposing fixes. Use when something is broken, not working, crashing, or throwing errors; triggers: debug, error, bug, exception, stack trace, not working, crash.
• 100systematic-debugging
  Step-by-step debugging workflow: reproduce the bug, isolate the failing component, trace to root cause, apply a targeted fix, and verify the fix resolves the issue without regressions. Use when you encounter a bug, error, exception, crash, or unexpected behavior that needs troubleshooting.
• 100acp-bug-fix
  Use when the user asks to fix a bug, investigate an error, debug a crash, explain a stack trace, or make a failing test pass. Enforces reproduce → isolate → smallest fix → verify, instead of guessing a cause and patching code.