Debug With Evidence: A Claude Skill for Root Causes
September 19, 2026
AI debugging goes wrong when the assistant edits code before it has evidence. The Empirical Diagnostician skill requires raw logs first, a diagnostic record that separates facts from inferences, competing hypotheses tested with read-only probes, and a written root-cause contract before any source file changes.
Why does AI debugging turn into trial and error?
Given an error, an assistant will often guess a cause from file names or directory structure, patch something plausible, and re-run. If the patch masks the symptom, the bug is "fixed" until it returns.
The skill exists to minimize trial-and-error edits and to require evidence-backed conclusions before any source file is modified. It applies whenever you ask Claude to debug a software error, a test failure, a crash, or unexpected behavior.
What are the seven stages?
| Stage | What Claude does |
|---|---|
| 1. Log and traceback extraction | Captures the raw, un-truncated error output, with exact error types, line numbers, and call stack frames verbatim |
| 2. Fast-Track evaluation | Decides whether the defect is a trivial single-token fix or needs the full process |
| 3. Diagnostic record | Separates user facts, repository evidence, inferences, and unknowns |
| 4. Hypothesis matrix | Writes two to three competing root causes, each with the log signature that would confirm or rule it out |
| 5. Minimal probes | Runs read-only diagnostics that distinguish between the hypotheses |
| 6. Root-cause contract | States the root cause, edit boundary, verification command, and non-goals, then makes the smallest justified edit |
| 7. Anti-patterns | Prohibits symptom masking, deleted assertions, and unverified "fixed" claims |
What is the Fast-Track?
For an unambiguous single-token defect, such as a SyntaxError on one line whose typo is obvious from the surrounding source, Claude records a short Fast-Track Decision (evidence, root cause, edit boundary, verification command) and skips ahead to the contract.
Fast-Track is off the table when the fix could depend on runtime state, more than one file, an external service, or an assumption the evidence doesn't confirm. Those go through the full process.
What goes in the diagnostic record?
The record has four sections, and the point is to keep them apart:
- User facts: goals and constraints from your prompt.
- Repository evidence: facts from source files, manifests, and terminal logs.
- Inferences: deductions that combine the two.
- Unknowns: missing details needed to verify the bug.
Claude updates it when a probe changes the evidence, and it does not treat an inference as a fact. The same fact-versus-inference separation appears in Context Cartographer.
How does the hypothesis matrix work?
Claude writes at least two or three competing hypotheses, drawn from three categories, and records the expected log signature for each.
| Category | Type | Examples |
|---|---|---|
| A | State or logic violation | Incorrect variable mutation, race condition, unhandled null state |
| B | Contract drift | Caller arguments that don't match the receiver's signature, schema changes |
| C | Environment or config | Missing environment variables, version mismatches, dependency failures |
A probe only counts as proof if its output tells the hypotheses apart. A probe that fits every hypothesis proves nothing.
What is the root-cause contract?
Before editing, Claude writes four lines:
- Identified root cause: the exact broken invariant in the code.
- Minimal edit boundary: the specific lines and functions it will change.
- Verification command: the exact command (for example
pytest,npm test,cargo check) that confirms the fix. - Non-goals: what it will not modify.
It then makes the smallest justified edit, runs the verification command, and reports the actual result.
What does the skill forbid?
- Symptom masking: no generic try-catch blocks or dummy return values to silence an error.
- Deleting or commenting out existing test assertions to make tests pass.
- Declaring a bug fixed without clean execution shown in terminal output.
- Altering your stack traces, CLI flags, or file paths.
What do the worked examples show?
| Example | Path taken |
|---|---|
A test run reports SyntaxError on one line, and the typo is unambiguous |
Fast-Track: record the decision, make only the syntax edit, run the narrowest relevant check |
| A failing integration test shows an unexpected response with an unclear stack trace | Full process: diagnostic record, competing hypotheses, a read-only probe, then the contract before any edit |
How do I install it?
- Download
empirical-diagnostician.md. - Save it as
.claude/skills/empirical-diagnostician/SKILL.mdin your project or in~/.claude/skills/. - Ask Claude to debug an error or investigate a failing test.
It is also in the GitHub repository, alongside the other skills.
FAQ
Does this slow down simple fixes?
Not for unambiguous single-token defects. Fast-Track skips the full process for those, while still requiring evidence and a verification command.
Why forbid try-catch blocks?
A generic try-catch or dummy return value hides the error without fixing the cause, so the bug returns later in a harder-to-find form.
What if the stack trace is incomplete?
Claude runs the narrowest applicable diagnostic command to capture the logs it needs. It does not guess a root cause from directory structure or file names alone.
Does the skill change my files?
Only at the end, and only within the edit boundary written in the root-cause contract. Probes are read-only.
Related: Prompt Evaluation Engineer applies the same evidence-first discipline to testing prompts.