Debugging

Debugging

Iron Law

NO FIX WITHOUT ROOT-CAUSE EVIDENCE.

When to Use

• Investigating defects, flakes, timing-sensitive bugs, regressions,

production incidents, unclear failures, or "stuck" debugging sessions.

When NOT to Use

• Planned refactors with no failing behavior; use refactoring.
• Performance investigation where the symptom is slowness; use

performance.

• Git-history regression search mechanics; pair with git-workflow.

Core Ideas

1. Reproduce before fixing. Change one variable per experiment.
2. Reduce the failing case until only the bug remains. Localize by

boundary: data, service, integration, application, infrastructure.

1. Debugging should improve the human's failure model with evidence.
2. Fix causes, not symptoms.
3. For incidents, produce blameless learning with owned follow-up

actions, never "human error" as a root cause.

Workflow

1. Capture the exact symptom: command, input, output, stack trace,

timing, environment. Reproduce reliably or record why reproduction isn't yet possible.

1. After the third experiment, keep a short debug log. Form one

hypothesis at a time, predict what else must be true, run the smallest experiment that confirms or refutes it.

1. Before editing, state the current failure model: likely cause,

evidence for it, and the observation that would disprove it.

1. Fix the identified cause. Add a regression test or operational

guard before declaring fixed.

Verification

• [ ] The bug reproduces on pre-fix code or non-reproducibility is

documented.

• [ ] The root cause is named in one sentence, explains all observed

symptoms, and identifies evidence that ruled out main alternatives.

• [ ] The fix is one atomic change aimed at that cause, with a

regression test or equivalent guard that fails before and passes after.

• [ ] Timing-sensitive bugs were verified with non-invasive observation or

replay.

• [ ] Incident follow-ups have owners and deadlines.
• [ ] Unproven root-cause or fix claims are reported as unproven.

Tripwires

| Trigger | Do this instead | False alarm | |---|---|---| | "Probably X, let me try fixing" | Gather evidence that confirms X before editing. | The user asked for a speculative explanation, not a fix. | | "No time to reproduce" | Create the smallest reproduction or state why reproduction is blocked. | Production-only incident where logs/traces are the available reproduction. | | "One more guess and it'll work" | Stop editing. Collect a new observation that changes the model. | A syntax or wiring typo found directly in the failing output. | | "The agent found a fix but I can't explain the bug" | Stop and rebuild the failure model before editing further. | Disposable local experiment with no completion claim. | | "Fixed it locally, ship it" | Name the root cause and add or run the regression guard. | Local run is the requested diagnostic, not a completion claim. | | "Flake - just retry" | Treat the flake as a bug and identify whether test, code, or environment failed. | Infrastructure outage already confirmed outside the code under review. | | "Probably a race condition" | Show interleaving, shared state, or timing evidence before changing concurrency code. | The race is already demonstrated by a failing sanitizer or trace. |

Handoffs

• Use proof for fix-claim evidence and the regression test shape.
• Use git-workflow for git bisect, reflog recovery, or conflict-heavy

debugging.

• Use observability when the right evidence must come from logs,

metrics, traces, or incident timelines.

• Use error-handling when the root cause is an error boundary,

retry, timeout, or recovery contract.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: kreek
• Source: kreek/consult
• License: MIT

Install and usage instructions live in the source repository linked above.