debug-agent

# Debug a Bug 1. Establish the expected behavior, reproduction, affected environment, and success criteria. Inspect file history when the report identifies a file or line. 2. Trace the real execution path. Use existing tests, stack traces, logs, and runtime evidence before creating more instrumentation. 3. State the plausible causes and choose the cheapest check that distinguishes them. A failing regression test or deterministic source-level error can be sufficient; not every bug needs a logging server. 4. Reproduce autonomously using available tools when possible. Ask for a user-only reproduction step only when access or missing information prevents progress; reuse the agreed method in later iterations. 5. Apply the smallest fix supported by the evidence, preserving unrelated changes. 6. Verify the original failure and relevant edge cases. Follow the repository's verification requirements once for the final state. 7. Remove temporary instrumentation and files owned by this task after verification, and report the cause, fix, and evidence. Do not require another confirmation when the authorized automated check proves success. ## When instrumentation is needed - Add a small number of logs tied to specific hypotheses; avoid credentials, personal data, and arbitrary content dumps. - Prefer the application's existing logger or test harness. Use an existing local debug service if useful; do not install or require a new daemon by default. - Use a task-specific log file and mark temporary code clearly. Never clear another session's logs. - Collect before/after evidence. If a hypothesis fails, remove its speculative fix and revise the investigation. - If user-only verification remains pending, state the limitation and retain only the instrumentation needed for that verification, unless the user requests cleanup.