Skill: Debug Assist

What This Skill Does

Provides a systematic debugging workflow that prevents the common problem of circular debugging (try something → doesn't work → try something else → forget what was tried → repeat). Logs all hypotheses and results as a debugging trace.

When to Use

• When a bug is non-trivial (not an obvious typo)

• When initial fix attempts haven't worked

• When the user says "I can't figure out why X happens"

Execution Model

• Always: the primary agent runs this skill directly.

• Output: chat-based debugging trace + the fix itself.

Workflow

Step 1: Define the Bug

Clarify with the question tool:

• What's the expected behavior?

• What's the actual behavior?

• When did it start? (after a specific change? always?)

• Is it reproducible? (always, sometimes, only in certain conditions?)

Step 2: Reproduce

Reproduce the bug locally:

Run the failing scenario

<command that triggers the bug>

If it doesn't reproduce → it's environment-specific. Check: OS, versions, configuration, data.

Log: "Reproduced: Yes/No, with command: X"

Step 3: Isolate

Narrow down the failure:

• Which file is the error in? (from stack trace or error message)

• Which function fails? (add logging if needed)

• Which input triggers it? (test with minimal input)

Log: "Isolated to: :, triggered by: "

Step 4: Hypothesize

List possible causes (max 3):

• Hypothesis A:

• Hypothesis B:

• Hypothesis C:

Do NOT fix yet. Just list hypotheses.

Step 5: Verify

Test each hypothesis:

• Add targeted logging or assertions

• Run the failing scenario

• Check which hypothesis matches

Log each result: "Hypothesis A: confirmed/rejected because "

Step 6: Fix

Apply the minimal fix for the confirmed hypothesis.

• One change: fix only the confirmed root cause

• No refactoring: fix the bug, nothing else

Step 7: Test

• Run the original failing scenario → must pass

• Run the full test suite → no regressions

• Remove any debugging logging

Step 8: Document

If the bug was non-obvious, document it:

• What was the root cause?

• Why was it non-obvious?

• How to prevent it in the future?

Consider creating a test case that specifically prevents regression.

Rules

• Log the path: every hypothesis and its result must be recorded. This prevents circular debugging.

• Reproduce first: never fix a bug you can't reproduce. You won't know if the fix works.

• Isolate before fixing: narrow down to the smallest possible scope before changing code.

• One hypothesis at a time: test one hypothesis, get a result, then move to the next.

• Minimal fix: fix only the bug. No improvements, no refactoring, no "while I'm here."

• No built-in explore agent: do NOT use the built-in explore subagent type.