| name | empirical-diagnostician |
| description | This skill helps Claude perform evidence-based debugging and empirical diagnosis to identify root causes of coding issues systematically. |
Empirical Diagnosis and Evidence-Based Debugging
When users request debugging assistance for software errors, test failures, crashes, or unexpected behaviors, utilize this skill to minimize trial-and-error adjustments and ensure evidence-backed conclusions before modifying any source files.
Instructions
When a user asks to debug an error or investigate a problem, follow these steps:
Stage 1: Mandatory Log and Traceback Extraction
- Extract the raw, un-truncated error log, stack trace, or terminal output.
- Capture exact error types, line numbers, variable states, and call stack frames verbatim.
- If the stack trace is incomplete, use the Bash tool to run the narrowest applicable diagnostic command to capture the necessary logs.
- Do not guess root causes based on directory structures or file names alone.
Stage 2: Fast-Track Evaluation
- Evaluate defect complexity:
- Fast-Track Bypass: If you identify an unambiguous single-token defect, record a minimal Fast-Track Decision including evidence, root cause, edit boundary, and verification command. Continue directly to Stage 6 (Root-Cause Contract). Do not use Fast-Track if the fix depends on runtime state, multiple files, external services, or unverified assumptions — continue to Stage 3 instead.
- Standard Track: If the defect involves state or logic issues, multi-file execution, schema or contract mismatches, configuration problems, or unclear runtime crashes, proceed to Stage 3.
Stage 3: Diagnostic Record and Fact Separation
- Publish a concise diagnostic record containing these four distinct sections:
### Diagnostic Record
- **User Facts:** Goals and constraints provided in the prompt.
- **Repository Evidence:** Facts from local source files, manifests, and terminal logs.
- **Inferences:** Deductions combining user facts with repository evidence.
- **Unknowns:** Missing details required to verify the bug.
- Keep the record concise and update it when a probe changes the evidence. Do not treat inferences as definitive facts.
Stage 4: Hypothesis Matrix Formulation
- Formulate a structured hypothesis matrix with at least two to three competing root-cause hypotheses categorized as follows:
- Category A (State / Logic Violation): Incorrect variable mutation, race condition, or unhandled null state.
- Category B (Contract Drift): Mismatch between caller arguments and recipient signatures, or schema changes.
- Category C (Environment / Config): Missing environment variables, version mismatches, or dependency failures.
- For each hypothesis, document the expected log signature that would confirm or invalidate it.
Stage 5: Minimal Non-Destructive Probes
- Execute minimal, read-only diagnostic probes to isolate the failing branch:
- Run targeted single-test commands or targeted print/log assertions.
- Evaluate probe outputs against the hypothesis matrix to eliminate false leads.
- Do not treat a probe as proof unless its output distinguishes between the competing hypotheses.
Stage 6: Root-Cause Contract and Verification
- Once the root cause is isolated, construct a concise task contract containing:
### Root-Cause Contract
- **Identified Root Cause:** The exact broken invariant in code.
- **Minimal Edit Boundary:** Specific lines and functions to be modified.
- **Verification Command:** Exact terminal command (e.g., pytest, npm test, cargo check) to confirm the fix.
- **Non-Goals:** Explicit boundaries of what will not be modified.
- Use this contract to make the smallest justified edit, execute the specified verification command, and report its actual result.
Stage 7: Anti-Patterns and Prohibitions
- Do not engage in symptom masking; avoid using generic try-catch blocks or returning dummy values to silence errors.
- Never delete or comment out existing test assertions to make tests pass.
- Do not declare a bug fixed without confirming clean execution through terminal output.
- Refrain from altering user-supplied stack traces, CLI flags, or file paths.
Example Usage
Example 1: Fast-Track syntax defect
- Input: A test run reports
SyntaxError on one line.
- Action: Record a minimal Fast-Track Decision, make only the syntax edit, and run the narrowest relevant test or parser check.
- Do not do: Avoid Fast-Track if the failure could depend on runtime state, multiple files, an external service, or unverified assumptions.
Example 2: Stateful failing test
- Input: A failing integration test shows an unexpected response with an unclear stack trace.
- Action: Publish the Diagnostic Record, build competing hypotheses, run a read-only probe to distinguish them, and write the Root-Cause Contract before making edits.
- Verification: Execute the specified test command and report its actual terminal output.
Worked Examples
Example 1: Fast-Track syntax defect
- Input: A test run reports
SyntaxError on one line in one file, and the surrounding source makes the typo unambiguous.
- Action: Record a minimal Fast-Track Decision, make only the syntax edit, and run the narrowest relevant test or parser check.
- Do not do: Do not use Fast-Track if the failure could depend on runtime state, more than one file, an external service, or an assumption not confirmed by evidence.
Example 2: Stateful failing test
- Input: A failing integration test shows an unexpected response, but the stack trace does not identify whether the cause is state, contract drift, or configuration.
- Action: Publish the Diagnostic Record, build competing hypotheses, run a read-only probe that distinguishes them, then write the Root-Cause Contract before editing.
- Verification: Run the specified test command and report its actual terminal result.
