| 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:
-
State hypothesis explicitly — What do you think is causing this? Don't jump to fixing.
-
Trace through real data — Use actual logs, events, or runtime values to verify the hypothesis. Show the concrete path from input to unexpected output.
-
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.
-
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?"
-
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.
