Debugging Guide

When to Use This Skill

Use this skill when the user asks you to:

• debug a bug, regression, crash, or failing test
• investigate unexpected behavior or incorrect output
• trace request flow, state changes, or data transformations
• add temporary instrumentation to confirm or reject a hypothesis
• isolate the root cause before making a fix

Core Principles

1. Debug the root cause, not the symptom.
2. Instrument narrowly. Add the smallest amount of temporary logging needed to test the current hypothesis.
3. Keep logs readable. Temporary logs must be useful to both the agent and the user without excess noise.
4. Prefer file-based debug output over scattered console spam.
5. Clean up completely. Remove temporary logging code and delete session log files when the debugging session is finished.