Home / debugging
Debugging
Six skills for finding the cause of a failure: minimise a bug reproduction, cluster log lines, find flaky tests in JUnit XML, explain a stack trace, summarise a py-spy, pprof or cProfile profile, and work a memory leak checklist.
Install
In Claude Code, add the marketplace and install the plugin:
/plugin marketplace add basitalisandhu/claude-skills
/plugin install debugging@claude-skills
Or copy the skill files into ~/.claude/skills/ from a clone:
git clone https://github.com/basitalisandhu/claude-skills
cd claude-skills
python3 install.py --user --only debugging
Skills
| Skill | What it does | Scripts |
|---|---|---|
| bug-repro-minimiser | Turn a vague bug report or a long failing script into the smallest reliable reproduction: reduce it to a single command or test that fails every time and still shows the bug, with the environment, input and expected versus actual result pinned down. | no |
| flaky-test-hunter | Find tests that pass and fail without code changes by comparing JUnit XML reports from several runs with a bundled script, then classify each flaky test by cause (ordering, timing, shared state, resources, environment) and prescribe the fix. | yes |
| log-triage | Reduce a large log file or production log dump to its distinct message templates with counts, levels, first and last occurrence and attached stack traces using a bundled clustering script, then rank what to look at first. | yes |
| memory-leak-checklist | Diagnose a service whose memory keeps growing or only goes up, with a fixed checklist: confirm it is a real leak and not a cache warming up or fragmentation, measure with heap tools (tracemalloc, objgraph, Node heap snapshots, Go pprof heap, JVM histograms), follow the retaining paths to what holds the objects, and fix the usual causes (unbounded caches, listeners, closures, registries, pools). | no |
| perf-profile-reader | Read a captured CPU profile (py-spy collapsed stacks or dump, Go pprof text output, Python cProfile output) with a bundled script, find the few functions and calls that hold the time, say whether it is real work or waiting, and what to optimise or fix first. | yes |
| stack-trace-explainer | Explain a stack trace, traceback, panic or crash from Python, JavaScript and Node, Java and the JVM, Go, Rust, .NET, Ruby or PHP: which frame holds the real fault versus where it surfaced (including a Caused by chain), what the error type means, and what to check next. | no |
Plugin README
Six skills for finding the cause of a failure: minimise a bug reproduction, cluster log lines, find flaky tests across JUnit reports, explain a stack trace, read a CPU profile, and work a memory leak checklist.
Find this when you search for: race condition, core dump or segfault, CI fails randomly.
Install
/plugin marketplace add basitalisandhu/claude-dev-skills
/plugin install debugging@claude-dev-skills
Skills then appear as /debugging:<skill>. Scripts need Python 3.11 or newer on PATH as python3; they use the standard library only and make no network calls.
Skills
| Skill | Triggers on | Produces |
|---|---|---|
bug-repro-minimiser | "sometimes", "on my machine", before a fix | smallest deterministic reproduction and a regression test |
log-triage | a log dump, CI log, "logs full of errors" | log_triage.py templates with counts, the three things to investigate |
flaky-test-hunter | CI fails intermittently, "is this flaky?" | flaky_test_hunter.py flaky list with cause and fix |
stack-trace-explainer | a pasted trace, "what does this mean?" | root cause in the chain, project frame, hypothesis, next check |
perf-profile-reader | a py-spy, pprof or cProfile capture | perf_profile_reader.py top frames, busy versus waiting, candidates |
memory-leak-checklist | memory grows until restart, OOM kills | confirm, measure, retaining path, suspect, fix, verify |
Tests for every script live in the repository's tests/ directory; run python3 -m pytest -q at the repository root.
Sample output
flaky-test-hunter on three JUnit XML reports from the same pytest suite, where the checkout test timed out in two runs and the migration test failed in all three:
$ python3 "${CLAUDE_PLUGIN_ROOT}/skills/flaky-test-hunter/scripts/flaky_test_hunter.py" ci-runs/
flaky-test-hunter 0.1.0: 3 runs, 3 distinct tests, 1 flaky, 1 always failing
run ci-runs/run-1.xml: 3 tests, 2 failed, 0 skipped
run ci-runs/run-2.xml: 3 tests, 1 failed, 0 skipped
run ci-runs/run-3.xml: 3 tests, 2 failed, 0 skipped
flaky (passed and failed across runs):
tests.test_api::test_checkout pass=1 fail=2 rate=0.667 reruns=0 time=2.1-5.02s
TimeoutError: payment stub did not answer in 5s
always failing (not flaky, broken):
tests.test_db::test_migrate fail=3 AssertionError: expected 12 tables, found 11
exit 0