debugging
/debugging
Use when a bug's cause is unknown. Applies a hypothesis-driven method — reproduce, isolate, instrument, prove — instead of speculative edits, and covers profiler, debugger, and log-based investigation. Trigger on "no idea why this is failing", "works locally but not in prod", "this test fails intermittently", "it got slower and i don't know why". Do not use once the cause is known and needs a tested fix — see the bug-fix-protocol skill.
- Author
- nimadorostkar ↗
- Repository
- Claude-Skills-collection ↗
- Licence
- MIT
- Last repository change
- 24.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 24.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Use when a bug's cause is unknown. Applies a hypothesis-driven method — reproduce, isolate, instrument, prove — instead of speculative edits, and covers profiler, debugger, and log-based investigation. Trigger on "no idea why this is failing", "works locally but not in prod", "this test fails intermittently", "it got slower and i don't know why". Do not use once the cause is known and needs a tested fix — see the bug-fix-protocol skill.
Triggers from the description
Original author description
Use when a bug's cause is unknown. Applies a hypothesis-driven method — reproduce, isolate, instrument, prove — instead of speculative edits, and covers profiler, debugger, and log-based investigation. Trigger on "no idea why this is failing", "works locally but not in prod", "this test fails intermittently", "it got slower and i don't know why". Do not use once the cause is known and needs a tested fix — see the bug-fix-protocol skill.
How it works
- Purpose
- When to Use
- Capabilities
- Inputs
- Outputs
- Workflow
- Best Practices
- Examples
- Notes
SKILL.md preview
---
name: debugging
description: Use when a bug's cause is unknown. Applies a hypothesis-driven method — reproduce, isolate, instrument, prove — instead of speculative edits, and covers profiler, debugger, and log-based investigation. Trigger on "no idea why this is failing", "works locally but not in prod", "this test fails intermittently", "it got slower and i don't know why". Do not use once the cause is known and needs a tested fix — see the bug-fix-protocol skill.
metadata:
category: development
version: 1.0.0
tags: [debugging, root-cause, diagnostics, profiling]
---
# Debugging
## Purpose
Find the actual cause of a defect, not a change that makes the symptom disappear. Debugging is a search problem, and the method is binary search over hypotheses.
## When to Use
- A test fails and the reason is not obvious from the assertion.
- Production behavior differs from local behavior.
- An intermittent or timing-dependent failure.
- A performance regression with no obvious cause.
- A bug that "came back" after being fixed.
## Capabilities
- Deterministic reproduction, including of flaky failures.
- Bisection over code history, input space, and configuration.
- Instrumentation: strategic logging, breakpoints, tracing, core dumps.
- Concurrency debugging: race detectors, deadlock analysis, lock ordering.
- Performance debugging: CPU and allocation profiles, flame graphs.
## Inputs
- The failure: error message, stack trace, failing test, or observed behavior.
- The last known-good state, if any.
- Environment differences between where it fails and where it does not.
## Outputs
- A reproduction that fails reliably.
- A stated root cause, with the evidence that proves it.
- A fix, plus a regression test that fails without the fix.
## Workflow
1. **Reproduce** — Reduce to the smallest input and shortest path that still fails. If you cannot reproduce it, you cannot verify a fix. For flaky failures, run in a loop until you have a failure rate.
2. **Read the evidence** — Read the entire stack trace, including the parts you have seen before. Read the actual error, not the one you assume it is.
3. **Form one hypothesis** — State it as a falsifiable claim: "the cache returns a stale value because the invalidation runs before the write commits."
4. **Test the hypothesis** — Add instrumentation that would distinguish true from false. Do not change behavior yet.
5. **Bisect** — If no hypothesis survives, bisect. `git bisect` over commits; comment out halves of the input; disable half the config.
6. **Prove the cause** — You have the cause when you can turn the bug on and off at will.
7. **Fix and regress** — Write the failing test first, then fix, then confirm the test passes and the rest still do.
## Best Practices
- Never change two things at once. You will not know which one mattered.
- "It works now" without an explanation means the bug is still there.
- Trust the machine over your memory of what the code does — read the code that is running, on the branch that is deployed.
- If the bug is in a dependency, prove it with a minimal script before reporting or working around it.
- Timing-dependent bugs are nearly always missing synchronization or an assumed ordering. Look for shared mutable state first.
- Delete instrumentation you added, or promote it to permanent, structured logging. Do not leave debug prints behind.
## Examples
**Hypothesis log for an intermittent failure:**
```text
Symptom : /checkout returns 500 approximately 1 in 40 requests under load.
Evidence: Stack trace shows NullPointerException in CartCache.get(); no error at low load.
H1: Cache eviction races with read.
Test: log cache size + key on every get/put; run 500 concurrent requests.
Result: FALSE — evictions never coincide with the failures.
H2: Cart is written by request thread but read by an async pricing task
before the write commits.
Test: log thread id and transaction id at write and at read.
Result: TRUE — pricing task reads on a different connection, 3-8ms before commit.
Cause: Async task enqueued inside the transaction, executed outside it.
Fix : Enqueue on transaction commit (after-commit hook).
Test : Regression test asserting the task is not enqueued until commit.
```
## Notes
- `git bisect run <script>` automates bisection completely when you have a scripted reproduction. It is the single highest-leverage debugging tool most engineers underuse.
- Heisenbugs that vanish under a debugger are usually timing or optimization-related. Reach for logging and race detectors instead of breakpoints.
- A bug that reappears was never fixed — the original fix addressed a symptom. Reopen the investigation rather than patching again.
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · nimadorostkar/Claude-Skills-collection | 100 | MIT |
| sentimony/skills | 100 | MIT |
| sentimony/skills | 100 | MIT |
| wrongstack/wrongstack | 100 | MIT |
| dxos/dxos | 100 | Apache-2.0 |
| iliaal/ai-skills | 100 | MIT |
| t8jwscc7qy-sketch/foma-skills | 100 | Apache-2.0 |
| arxdsilva/ai-loops | 100 | MIT |
| zts212653/clowder-ai | 100 | MIT |
Database snapshot: 13.11.2026 · package version 2197dc340e4c (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
- 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. - 100systematic-debugging
Four-phase debugging - reproduce, isolate, root cause, fix behind a failing regression test; use for any bug or failure. - 91systematic-debugging
Use when a bug, failing or flaky test, production incident, unexpected output, or performance regression has an unknown cause. - 90root-cause-debugging
Use when diagnosing a bug, failing test, crash, or wrong output. A disciplined, hypothesis-driven method for finding the true root cause from evidence instead of guessing or masking symptoms. Use before writing any fix. - 100debug
Use when encountering a bug, test failure, unexpected behavior, or when the user asks for help debugging. Hypothesis-driven — reproduce, investigate, fix, verify. Standalone — works outside the plan/spec/build workflow. - 90debugging-workflow
Reproduce, isolate, and fix unexplained failures, regressions, or flaky behavior. Use when the cause is uncertain; a known-cause fix usually needs only the normal implementation workflow.