# Systematic Debugging

> Use when a bug, failing or flaky test, production incident, unexpected output, or performance regression has an unknown cause.

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

---


# Systematic Debugging

Find the root cause before attempting a fix. A symptom patch without a causal
explanation creates a second unknown.

Read the complete failure and reproduce it with the smallest reliable loop.
Trace the bad value or condition backward across boundaries, compare it with a
working path, and inspect recent changes without assuming they are causal. For
flakiness, identify nondeterministic input, timing, shared state, or resource
contention instead of retrying until green.

If output is filtered or truncated, retrieve the relevant raw diagnostics before
diagnosing the failure. If raw evidence remains unavailable or incomplete, treat
the diagnosis as inconclusive. Recover missing context through bounded reads.
Do not repeat a side effect solely to recover output.

Before choosing the fix location, inspect callers of the implicated code and
identify whether they depend on a shared invariant. Add regression coverage for
sibling paths affected by the same cause, including paths absent from the
report. Fix the invariant where it belongs; avoid unrelated caller cleanup.

Treat the execution environment as a suspect. When a sandbox, permission
layer, or harness restriction can explain the failure, re-run the probe
outside that restriction before declaring a tool, service, or dependency
broken.

State one evidence-backed hypothesis and test the cheapest decisive prediction
while changing one variable. A failed hypothesis is evidence; update the model
before trying another. After the cause is confirmed, write and run a failing
regression test at a stable boundary before changing production code. Make the
smallest cause-level fix, then run the regression, relevant checks, and the
original failure path.

When a deterministic local test is impossible, agree on a substitute oracle
and record the environment, correlation key, pre-change failure, post-change
result, and monitoring window. After three failed fixes on one approach, stop,
report the evidence and remaining uncertainty, and reconsider the design.