/investigate

name: investigate
description: "Find the root cause of bugs, test failures, build errors, or performance issues by testing hypotheses. Use when the user asks to \"investigate this bug\", \"debug this\", or \"find the root cause\"."

Investigate

Systematic methodology for finding the root cause of bugs, failures, and unexpected behavior. Cycle through characterize-isolate-hypothesize-test steps, with oracle escalation for hard problems. Diagnose the root cause — do not apply fixes.

Optional: `$ARGUMENTS` contains the problem description or error message.

Step 1: Characterize

Gather the symptom and establish what is actually happening:

1. **Collect evidence** — error message, stack trace, test output, log entries, or user description of unexpected behavior 2. **Classify the problem type**:

| Signal | Type | |--------|------| | Stack trace / exception | Runtime error | | Test assertion failure | Test failure | | Compilation / bundler / build error | Build failure | | Type checker error (tsc, mypy, pyright) | Type error | | Slow response / high CPU / memory growth | Performance | | "It does X instead of Y" / no error | Unexpected behavior |

3. **Establish reproduction** — run the failing command, test, or operation, and confirm its output shows the reported symptom rather than a neighboring failure. When no command at hand shows the symptom, build one, trying whichever of these fit, in this order:

• A test at the boundary that reaches the failure
• A script that drives the running system from outside and asserts on what it returns
• A captured request, payload, or event log replayed through the failing path
• The same input run through a known-good version and the current one, with the outputs compared
• Many generated inputs, when the failure appears for only some
• For an intermittent failure, the trigger repeated or run concurrently until it fails often enough to test against

Reproduction is established when one command has been run and its output shows the reported symptom. Record that command and its output for verification. For intermittent or long-running reproductions, use the Monitor tool to tail logs filtered for relevant signals (errors, stack traces, specific identifiers) so failures surface live while you work.

When neither the failing command nor any reproduction built from the list above shows the symptom, output what was tried and what each attempt showed. Then use `AskUserQuestion` to offer three ways forward, and act on the answer:

• **Provide access or an artifact** — the user supplies an environment where the failure occurs, or a capture from one such as a log, a trace, or a recorded request. Return to item 3 with it.
• **Allow temporary instrumentation** — add labeled logging where the failure occurs, have the user trigger the failure, and read what it recorded. Remove the logging once it has been read, and confirm with `git diff -- <file>` that each file is back to its pre-check state. Carry what it recorded into Step 2 as evidence. When it yields a command whose output shows the symptom, record that command as the reproduction; otherwise continue as under **Proceed without a reproduction**.
• **Proceed without a reproduction** — document the constraints and continue on historical evidence. Mark Step 4 verdicts and the report's root cause `unverified by reproduction`, and give the report's reproduction command as `none`, followed by what was tried. When a later step produces a command whose output shows the symptom, record that command from then on and drop the mark.

Minimize the Reproduction

Cut the reproduction down in a throwaway copy, leaving the working tree and its git index unchanged. Remove inputs, configuration, data, callers, and steps, halving what remains before cutting single elements. Re-run after each cut and restore a cut that makes the symptom disappear. Stop when removing any remaining element makes the symptom disappear, or once the reproduction runs quickly and its remaining elements can be named. Record the minimal command alongside the original, with what was cut, then delete the copy and report anything that could not be deleted. The original stays the report's reproduction command. **Skip** when the reproduction is a single test or command with nothing left to remove, when each run is slow or intermittent, or when no reproduction exists.

Step 2: Isolate

Narrow from "something is wrong" to "the problem is in this area." Read [references/problem-type-playbooks.md](references/problem-type-playbooks.md) for type-specific first moves and tool sequences.

Git Archeology

For all problem types, check what changed recently near the failure point:

git log --oneline -20 -- <file>
git blame -L <start>,<end> <file>

If a known-good state exists (e.g., "this worked yesterday"), consider `git bisect` to pinpoint the breaking commit.

When the problem description names a version, tag, or build that differs from the ref under investigation, resolve it to a ref and read what changed on the failing path between the two before generating hypotheses:

git diff <reported-ref>..HEAD -- <failing-path-files>

Read the full diff rather than its `--stat` summary. Carry each difference that could produce the symptom forward as a ranked hypothesis.

Upstream Issue Search

When the failure surfaces inside a third-party dependency, search its issue tracker for a distinctive string from the error before reading deeper into the dependency's code. An issue whose symptom matches often names the cause and the fix outright. Carry a match forward as a ranked hypothesis and test it.

Scope Narrowing

• **Stack traces**: Read the throwing function and its callers — full functions, not just the flagged line
• **Test failures**: Read both the test and the system under test
• **Build errors**: Read the config file and the referenced source
• **Unexpected behavior**: Trace the data flow from input to