debug

Debugging Through Investigation

Help the user debug an issue through systematic investigation and hypothesis-driven problem solving. This is a conversation, not a fix-it script.

Start by understanding the issue, then reproduce it, form theories, investigate with evidence, and only fix once you understand the root cause.

The Process

Understanding the issue:

• Explore the codebase first — read relevant files to build context before asking questions
• Ask questions one at a time to understand the problem
• Prefer multiple choice questions when possible, but open-ended is fine too
• Only one question per message
• Focus on understanding: expected behavior, actual behavior, reproduction steps, when it started, what changed recently

Reproducing the issue:

• Attempt to reproduce the issue before investigating code
• If this is a frontend/browser issue and you see playwright_* tools available, use them:
  • playwright_navigate to load the page
  • playwright_screenshot to capture visual evidence
  • playwright_click / playwright_fill to interact with elements
  • playwright_evaluate to check console errors and state
• If this is a backend/CLI issue, run the reproduction steps with Bash
• If this is a test failure, run the specific failing test
• If you cannot reproduce, investigate why — environment, timing, specific data, concurrency
• Document the reproduction case clearly — you need it later to verify the fix

Forming hypotheses:

• Based on symptoms and code context, propose 2-3 theories about the root cause
• For each theory: description, likelihood (high/medium/low), how to test it
• Present theories to the user — they may have context that rules some out
• Wait for user input before proceeding

Investigating:

• Work through hypotheses starting with the most likely
• Read relevant code paths — use Glob and Grep to find files, Read to inspect
• Check logs, trace execution, inspect state
• Use Playwright for frontend state inspection if available
• Present findings as you go — if Theory A doesn't pan out, explain why and move to Theory B
• Once you identify the root cause with evidence, present it clearly and wait for confirmation: