git:20260924.3aceaab to git:20260924.17234b5

- description: Investigates bugs through hypothesis-driven root cause analysis and reports what is wrong before any fix. Automatically invoked when the user reports a bug, error, broken behavior, or something not working as expected. Use when something is broken, failing, or behaving unexpectedly.

- argument-hint: "[bug description, error message, or unexpected behavior]"

- Find the root cause of this bug and report it to the user.

-

- Your job is to find and explain the problem. Leave the fix for later. The only

- code you add is diagnostic logging, and only with the user's approval. Back

- every conclusion with evidence from code, logs, or commands.

-

- ## Phase 1: Understand the bug

-

- If `$ARGUMENTS` leaves them out, ask for:

- - expected behavior

- - observed behavior

- - steps to reproduce

-

- ### Categorize the bug

-

- Classify the issue early. Each type calls for a different strategy:

-

- | Category | Investigation Strategy |

- |---|---|

- | **Type / Compilation Error** | Check recent type changes, inference chains, tsconfig, package versions |

- | **Logic Error** | Trace data flow, check conditionals, compare with working code paths |

- | **Race Condition / Timing** | Look for shared state, async patterns, missing awaits, event ordering |

- | **State Management** | Trace state mutations, check store subscriptions, verify update propagation |

- | **Integration / API** | Check API contracts, data transformations, request/response shapes |

- | **Environment / Config** | Check env variables, config files, dependency versions, build settings |

- | **UI / Rendering** | Check component props, conditional rendering, CSS specificity, hydration |

-

- ### Verify reproduction

-

- Before investigating:

- - Confirm you know how to trigger the bug.

- - Note whether it's consistent or intermittent.

- - If reproducing it needs a running application, tell the user. They may need

- to reproduce it and send logs.

-

- ## Phase 2: Form hypotheses

-

- Before reading code, list 3-5 possible causes ranked by likelihood, based on

- the bug description, error messages, and common failure patterns:

-

- ```

- Hypotheses (ranked by likelihood):

- 1. [Most likely cause] - because [reasoning]

- 2. [Second most likely] - because [reasoning]

- 3. [Third most likely] - because [reasoning]

- ...

- ```

-

- A ranked list keeps you from locking onto the first plausible explanation. Test

- each one systematically.

-

- ## Phase 3: Investigate the root cause

-

- Trace the code to test your hypotheses. Use the `codebase-explorer` skill or an

- explorer subagent (Claude: `Explore`) for broad searches, and read files

- directly for targeted analysis.

-

- ### Techniques, most effective first

-

- 1. **Trace backward from the error.** Follow the call stack from the symptom to

- its origin.

- 2. **Check recently modified files first.** Most bugs live in recent changes.

- Use `git log --oneline -20 -- [relevant paths]`.

- 3. **Compare working and broken paths.** Find similar working code and list

- every difference.

- 4. **Trace data across boundaries.** Follow transformations between services

- and components (API → service → repository, or parent → child →

- grandchild).

- 5. **Check git blame and log.** Find the commit that introduced or changed the

- broken behavior.

-

- ### What to find

-

- - **What's wrong**: the specific code causing the incorrect behavior.

- - **When and how it was introduced**: the commit, PR, or change.

- - **Why it happened**: the underlying reason, such as a missed edge case, a

- wrong assumption, or an incomplete refactor.

-

- ### If the code makes the cause clear

-

- Tell the user right away, then go to Phase 5.

-

- ### If the cause is still unclear

-

- Tell the user:

- - what you've investigated so far

- - which hypotheses you've ruled out, and why

- - what remains unclear

-

- Then propose diagnostic logging. Explain what you want to log and why, and wait

- for approval.

-

- ## Phase 4: Diagnostic logging (only if needed)

-

- Enter this phase only when Phase 3 didn't find the cause.

-

- 1. Add targeted `console.log` statements prefixed with `[DEBUG-FIX]` to the

- suspected code paths.

- 2. Ask the user to reproduce the bug and paste the relevant logs.

- 3. Analyze the logs:

- - **Root cause found**: tell the user, then go to Phase 5.

- - **Still unclear**: explain what you learned, refine the hypotheses,

- propose more logging, and repeat with approval.

-

- ### When you're stuck

-

- After 3 or more inconclusive cycles (hypothesis, test, no answer):

-

- 1. **Summarize what's ruled out**: every hypothesis tested and the evidence

- against it.

- 2. **Change approach.** Form a new theory. Consider:

- - Is the bug in a different layer than assumed (backend or frontend,

- database or application)?

- - Could it be an environment or infrastructure issue?

- - Is there a timing or race condition that appears only under specific

- conditions?

- 3. **Ask the user.** They may have domain knowledge that changes the direction.

-

- ## Phase 5: Report and next steps

-

- Once you've found the root cause, present:

-

- ```

- ## Investigation Report

-

- **Root cause:** [one-line summary]

- **Confidence:** [High / Medium / Low] - [brief justification]

-

- **File(s):** [affected files with line numbers]

- **Introduced:** [commit hash / PR / approximate timeframe if known]

-

- **What needs to change:**

- - [description of the fix needed]

-

- **Why this happened:**

- - [brief explanation of the underlying cause - missed edge case, wrong assumption, incomplete refactor, etc.]

-

- **Next steps:**

- - `/create-plan [description]` - Create a fix plan

- - `/simple-plan [description]` - Quick fix plan if it's straightforward

- ```

-

- If you added diagnostic logs in Phase 4, remove every `[DEBUG-FIX]` log before

- finishing.

-

- ## Red flags

- Stop and reassess if you catch yourself:

- - proposing a fix before identifying the root cause

- - assuming a cause without evidence from the code

- - investigating code unrelated to the reported symptoms

- - testing variations of a failed hypothesis

- - saying "let's just try changing X and see if it works"

- - spending a long time without reporting intermediate findings

- Bug to investigate: $ARGUMENTS