Structured debugging workflow that prevents circular debugging. Follows a systematic approach of Reproduce, Isolate, Hypothesize, Verify, Fix, Test. Logs the debugging path as an artifact to avoid revisiting dead ends.
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
Structured debugging workflow that prevents circular debugging. Follows a systematic approach of Reproduce, Isolate, Hypothesize, Verify, Fix, Test. Logs the debugging path as an artifact to avoid revisiting dead ends.
license
MIT
compatibility
opencode
metadata
{"category":"workflow","phase":"debugging"}
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.
