Root-Cause Debugging Without Guess Fixes
Finds the real cause of a bug by reproducing, bisecting, and testing one hypothesis at a time before writing any fix.
Before & after
Same prompt, same agent — the only difference is the skill.
That's a frustrating issue. You've probably got some kind of race condition or a flaky dependency. Maybe the database is slow on Mondays? Or there's a rate limiter that kicks in? The obvious thing to check would be your logs—see if there's a pattern in what requests are hitting 403. You could add more logging around the authentication check and the permission validation. It might be something with how you're validating tokens or checking user roles. Have you looked at your infrastructure monitoring to see if there's a resource constraint on Mondays? Let me know what your auth flow looks like and I can suggest some things to try.
REPRODUCE PHASE → Set trap: Hit sign-up endpoint 1000 times. Mondays: 127 return 403 (12.7%). Other days: 3 return 403 (0.3%). → Confirm: Error happens ONLY on sign-up; login + update endpoints unaffected. Code identical in both; sign-up runs faster, hits DB less. → Isolate variable: Hypothesis—Monday batch job (user-import) holds connection pool lock 08:00-11:00 UTC. ISO LATE PHASE → Turn off Monday import job. Run 1000 sign-ups at 09:00 Monday. Result: 0% failure. Hypothesis confirmed. → Check: Connection pool exhaustion. Pool size: 10. Import job: 12 connections at 08:00. Sign-up needs 2. → Why permission validator? Auth code references stale connection (closed by timeout). Fallback to 403 instead of retry. TEST-THEN-PATCH ONLY → Don't rewrite connection pooling yet. Patch: isolate import job to named pool (pool-import) sized 5. Leave sign-up pool at 10. → Verify: Run 1000 sign-ups + import job simultaneously Monday 08:00. Zero 403s. Other-day tests unchanged. → Commit: 4-line change to pool config. No retry logic, no middleware changes.
About this skill
Your AI assistant sees an error, patches the line that crashed, and says it's fixed. Then the bug comes back, or a new one shows up. Sometimes a retry or a longer timeout just hides it. This skill makes Claude find the cause before it touches code. It reproduces the failure, narrows it by halving, and tests one written hypothesis at a time. Then it fixes the source, not the symptom.
What it does
- Reads errors properly: it finds the first failure, the deepest "caused by" entry, and the first stack frame in your own code, not just the last line.
- Turns flaky and intermittent bugs into measurable repros, with a run count large enough that "it passed" means something.
- Isolates by halving commits, inputs, tests, and layers (git bisect, delta-debugging), so it doesn't read code top to bottom.
- Ranks hypotheses and names the one experiment that tells them apart, with what each outcome means.
- Matches symptoms to the usual suspects: works locally but fails in CI, passes alone but fails in the suite, "nothing changed", or the bug vanishes when you add logging.
- Stops patching after three failed fixes and checks the assumptions instead, starting with whether the running code is the code you edited.
What you get
When the cause is obvious, you get a direct fix. Otherwise you get a short investigation report: symptom, repro, what was ruled out, ranked hypotheses, and the next experiment. Once the cause is confirmed, you get the root-cause fix, a regression test, and verification steps.
Best for
Developers stuck on intermittent, environment-specific, or "I already fixed this twice" bugs. Also anyone tired of AI tools that suppress symptoms instead of finding causes.
SKILL.md preview
---
name: root-cause-debugging-without-guess-fixes
description: Finds the root cause of a bug before any fix is written. It reproduces the failure, isolates it by halving (commits, inputs, tests, layers), and tests one written, falsifiable hypothesis at a time. Then it fixes the source and verifies against the original repro. Use when the user says "why is this failing", "debug this", "this test is flaky", "works on my machine but not in CI", "I already fixed this and it came back", "my API randomly times out", "nothing changed and now it's broken", or "stop guessing and find the actual cause".
---
# Root-Cause Debugging Without Guess Fixes
… (sign up to view the full skill)More development skills
View all Development skills →Performance Bottleneck Profiling: Node, Python, Go
Classifies a slowdown, gives exact profiler commands, reads the output, and proves the fix with same-conditions p95/p99 numbers.
Feature Scaffolding with Working Tests
Turn a short feature spec into code, runnable tests, and integration wiring that match your existing project.
Feature Flag Rollouts and Kill Switches
Design staged flag rollouts, verify rollback paths, and audit flag debt with explicit defaults, gates, and retirement plans.
Microcontroller Firmware and RTOS Engineering
Build and debug MCU firmware with bounded ISR/RTOS timing, safe DMA ownership, and measured power budgets.