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.