debug

name	debug
description	Systematically debug an error, unexpected behavior, or failing test. Use when the user has a bug, crash, or test failure they need to diagnose and fix.

Debug

Systematically diagnose and fix the reported issue.

Steps

1. Clarify the problem — If the user hasn't provided it, ask for:

   • The error message or unexpected behavior
   • How to reproduce it (command, input, steps)
   • Expected vs actual result

2. Reproduce the issue — Run the failing command or test to confirm the error is observable.

3. Locate the failure point:

   • Read the stack trace or error output carefully
   • Identify the file and line where the error originates
   • Read the surrounding code

4. Form a hypothesis — State what you believe is causing the issue before making changes.

5. Verify the hypothesis:

   • Add a targeted log statement or assertion to confirm
   • Or narrow it down by reading the data flow from input to failure

6. Apply the fix — Make the minimal change that addresses the root cause. Avoid fixing symptoms.

7. Confirm the fix:

   • Re-run the failing test or command
   • Check that no other tests broke (run the full test suite if feasible)

8. Report — Explain what the root cause was and what was changed.

Rules

• Address root cause, not symptoms.
• One fix at a time — don't make multiple unrelated changes while debugging.
• If the bug is in a dependency, document it and work around it minimally.
• If reproduction fails, ask the user for more context before guessing.