---
name: systematic-debugging-investigator
description: "Finds the real cause of a bug before any fix: reproduce it, narrow it, test one hypothesis at a time, then lock it in with a regression test. Use when a bug, flaky test or unexpected behavior needs its root cause found before anyone changes code. Do not use for fixing an obvious typo or reviewing code that has no reported failure. Related topics: coding, technical."
---

# Systematic Debugging Investigator

Finds the real cause of a bug before any fix: reproduce it, narrow it, test one hypothesis at a time, then lock it in with a regression test.

## When to use

Use this skill when a bug, flaky test or unexpected behavior needs its root cause found before anyone changes code. Do not use it for fixing an obvious typo or reviewing code that has no reported failure.

## Workflow

1. Ask the user for each input listed below in a single message, skipping any they have already given. Where options are listed, offer them, but accept other answers too.
2. Reproduce the failure reliably and record the exact steps, or state clearly that it could not be reproduced.
3. Bisect by commit, input, layer or code path, writing down each cut and what it ruled out.
4. State ranked hypotheses and test them one variable at a time, each with a check that could disprove it.
5. Explain the confirmed chain from root cause to symptom before proposing any change.
6. Apply the smallest fix and add a regression test that fails without it and passes with it.

## Inputs

- **Symptom** (longer free text)
- **Error output** (longer free text)
- **How to reproduce** (longer free text)
- **Recent changes** (free text, e.g. "Commits or deploys near when it started")
- **Environment** (free text, e.g. "Runtime and version and where it fails")
- **May modify code to investigate** (choose one: Yes, No)

## Output

An evidence log of reproduction, narrowing steps and hypotheses tested, then the root cause chain, the minimal fix and the regression test.

## Prompt template

Fill the inputs into this template and follow it as the full instruction.

### Systematic Debugging Investigator

Investigate this bug and do not propose a fix until the root cause is reproduced and confirmed.

- Symptom: {{Symptom}}
- Error output: {{Error output}}
- How to reproduce: {{How to reproduce}}
- Recent changes: {{Recent changes}}
- Environment: {{Environment}}
- May modify code to investigate: {{May modify code to investigate}}

Step one is a reliable reproduction; if there is none, find one before anything else and say how reliable it is. Then narrow the search by bisecting: by commit, by input, by layer or by code path, and record each cut. State hypotheses explicitly, ranked, and test one variable at a time with a check that could prove the hypothesis wrong. Keep a short evidence log of what was tried and what it showed. Once the root cause is confirmed, explain the chain from cause to symptom, then make the smallest fix and add a regression test that fails without it. If the bug is not reproduced after reasonable effort, say so and list what data would settle it instead of guessing.

## Pitfalls

- Changing several things at once, so a passing run cannot say which change mattered.
- Fixing the symptom, such as a null check, while the upstream cause keeps producing bad data.
- Declaring the bug fixed after one green run of an intermittent failure.