---
name: debug
description: Investigate and fix bugs. Use when the user reports a bug, failing behavior, regression, flaky case, crash, panic, incorrect output, or asks to debug an issue.
---

# Debug

## Goal

Turn vague bug reports into reproducible, verified fixes.

## Default workflow

1. **Define the failure clearly**
   - Restate the observed behavior, expected behavior, affected scope, and current evidence.
   - Before changing code, define a **verifiable success criterion** for the fix.

2. **Reproduce with a test first**
   - Prefer adding or updating an automated test that fails for the reported bug.
   - Reuse the project's existing test style and location.
   - If the bug is hard to express as a full test, create the smallest reproducible check possible (unit test, integration test, script, fixture, or command).

3. **Fix only after reproduction exists**
   - Change code only after you can reproduce the issue with a failing test/check, unless reproduction is impossible in the current environment.
   - Keep the fix scoped to the verified cause.

4. **Verify the fix**
   - Re-run the reproduction test/check and confirm it now passes.
   - Run the nearest related validation commands to catch regressions.

5. **If user cooperation is required**
   - Use `AskUser` to ask focused questions with choices when possible — this reduces back-and-forth.
   - Prepare everything the user needs before asking them to test:
     - exact command(s) to run
     - required environment variables / setup
     - expected output
     - log file path or log collection method
     - what result means success vs failure
   - Ask concise questions only after the test plan is ready.
   - When the user returns with logs/results, analyze both the logs and the user report before proposing the next step.

## Rules

- Prefer **test-first debugging** whenever the environment allows it.
- Do not claim a bug is fixed without a passing reproduction check or an explicit explanation of why local verification is impossible.
- If you cannot reproduce locally, say so clearly and switch to preparing the best user-runnable reproduction and logging plan.
- When asking the user to help test, minimize their work; prepare commands, paths, and logging details for them. Use `AskUser` to ask targeted questions — provide choices when possible to reduce ambiguity.
- Always report:
  - how the bug was reproduced
  - what changed
  - how the fix was verified
  - what remains uncertain
