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:

code

Root cause identified:
- File: [path:line]
- Problem: [what's wrong]
- Why: [explanation]
- Evidence: [what you observed]

Fixing:

•Propose the fix before implementing — the user may want a different approach
•Apply the minimal change that addresses the root cause
•Do not refactor unrelated code
•Add a test case for the bug if it wasn't covered by tests
•Add defensive checks or better error messages if appropriate

Verifying:

•Re-run the reproduction case — confirm the issue is fixed
•Run relevant tests — ensure nothing else broke
•Check related functionality for similar issues
•If Playwright is available, take a screenshot showing the fix works

Report

After fixing, provide a clear summary:

code

Debug session complete.

Issue: [brief description]
Root Cause: [what was wrong]
Fix: [what changed]

Files modified:
- [path] — [summary of changes]

Verification:
- [x] Issue no longer reproduces
- [x] Tests pass
- [x] Related functionality checked

Key Principles

•One question at a time — do not overwhelm
•Reproduce first — never skip this step
•Hypothesis-driven — do not make random changes
•Evidence-based — confirm theories with data, not guesses
•Minimal fixes — address the root cause, not symptoms
•Verify thoroughly — test the fix and related functionality
•Interactive — involve the user at key decision points
•Use Playwright when available — for frontend debugging, check your tool list for playwright_* tools

When to Stop and Escalate

Stop and ask the user for help if:

•You cannot reproduce the issue after multiple attempts
•The root cause requires domain knowledge you do not have
•The fix would require architectural changes beyond a targeted patch
•Multiple theories seem equally plausible and you need more context