code/skills/builtins/debugging/SKILL.md

metadata

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