Spaces:
Running
Running
feat(agent): add Claude Code-style agent, skills, slash-commands, hooks, todos, sandboxed workspace, and full-stack scaffolding
81aa0b5 verified | name: debugging | |
| description: Systematic debugging workflow for diagnosing and fixing errors. Use when the user reports a bug, crash, or unexpected behavior. | |
| language: any | |
| tags: debug, errors, troubleshooting, fix | |
| # Debugging | |
| Approach debugging systematically. Don't guess — investigate. | |
| ## Phase 1: Reproduce | |
| **Goal**: Make the bug happen reliably. | |
| - Ask: what exact steps trigger it? | |
| - Ask: what was the expected vs actual behavior? | |
| - Ask: is it consistent or intermittent? | |
| - If you can reproduce it locally, do so with `bash` and capture the full error output. | |
| ## Phase 2: Isolate | |
| **Goal**: Find the smallest scope where the bug reproduces. | |
| - Read the relevant code with `read_file` | |
| - Trace the data flow from input to failure point | |
| - Add temporary print/logging statements if needed | |
| - Identify the exact line where things go wrong | |
| ## Phase 3: Diagnose | |
| **Goal**: Understand WHY the bug happens. | |
| Common root causes: | |
| - **Null/None/undefined**: missing null checks | |
| - **Type confusion**: passing wrong type, silent coercion | |
| - **Off-by-one**: loop bounds, slicing | |
| - **Race conditions**: shared state, async ordering | |
| - **Stale state**: cached data not invalidated | |
| - **Wrong assumption**: code expects something the caller doesn't guarantee | |
| - **Environment**: missing env vars, wrong paths, permissions | |
| State the root cause in one sentence before fixing. | |
| ## Phase 4: Fix | |
| **Goal**: Apply the minimal correct fix. | |
| - Fix the root cause, not the symptom | |
| - Don't introduce new patterns — match the surrounding code style | |
| - Add a comment if the fix is non-obvious | |
| - Consider: are there other places with the same bug? | |
| ## Phase 5: Verify | |
| **Goal**: Confirm the fix works and doesn't break anything. | |
| - Re-run the reproduction steps | |
| - Run any existing tests with `bash` | |
| - Test edge cases related to the bug | |
| - Check that you haven't introduced regressions | |
| ## Phase 6: Document | |
| **Goal**: Prevent recurrence. | |
| - If appropriate, add a regression test | |
| - Update relevant docs/comments | |
| - Note the fix in the commit message | |
| ## Anti-patterns to avoid | |
| - ❌ Shotgun debugging: changing random things hoping it works | |
| - ❌ Fixing symptoms: papering over the real issue | |
| - ❌ Adding null checks everywhere: hiding the real bug | |
| - ❌ "Works on my machine": dismissing environmental factors | |
| - ❌ Skipping verification: assuming the fix works | |