investigate

name	investigate
description	Methodical investigation and root-cause analysis of bugs and issues before proposing solutions. Use when asked to investigate a bug, diagnose an issue, find the root cause of a problem, debug unexpected behavior, trace an error, or figure out why something is broken. Enforces hypothesis-driven debugging and avoids premature fixes.

Investigate

Methodical investigation protocol — understand before fixing.

Investigation Protocol

Before proposing any solution:

1. State hypothesis explicitly — What do you think is causing this? Don't jump to fixing.

2. Trace through real data — Use actual logs, events, or runtime values to verify the hypothesis. Show the concrete path from input to unexpected output.

3. Check the data structures — Before assuming timing/race conditions/complex state issues, verify the right fields are being accessed at the right levels. Many bugs are just wrong property paths.

4. Complexity check — If the proposed fix requires new state management, buffering, async coordination, or significant new abstractions, STOP and ask: "Is there a simpler explanation I'm missing?"

5. One concrete example — Walk through one specific failing case end-to-end before proposing a solution.

When in doubt: investigate more, propose less. Ask the user before committing to a solution direction.

Clarifying Questions

Use the ask_questions tool when:

• Multiple hypotheses are equally plausible and direction is needed
• Assumptions about expected behavior need confirmation
• The fix approach has tradeoffs requiring user decision
• Root cause is found but there are multiple valid solutions

Investigate first, then ask targeted questions to confirm direction before implementing.