Diagnose the root cause of a bug before applying the smallest correct fix.
NewMaintained
Automatic
◆Coding pack
Last verified 8/3/2026
What it changes
Passed 14 of 19 test cases with the skill, and 14 of 19 without it.
Without skill73%
With skill73%
Checks it passed that the model alone missed
Identifies the authentication logic change as high risk requiring risk review
1 fixed15 passed either way5 still failing1 broke
Pass-rate lift
0 pp
Tokens
+37%
Agent turns
0%
Response time
-22%
Model gemini-3.6-flashMeasured 8/3/2026v116 of 22 cases passed with skill · 19 comparable
Tokens, turns and time describe resource use, not a dollar price.
See it in action
A test case the skill fixed. Same model, same prompt, with and without the skill.
Prompt
A bug in `src/middleware/auth.ts` allows requests with expired JWT tokens to access private routes because token expiration checks are skipped when a `session_id` header is present. The fix requires altering how `session_id` and token expiration interact. What risk management step should be taken alongside the code fix?
What was checked, without and with the skill
Checked
Without skill
With skill
Identifies the authentication logic change as high risk requiring risk review
Missed
Passed
case-11 · gemini-3.6-flash · 8/3/2026 · answers are capped and redacted
What's inside
The instructions your model reads when the skill loads.
SKILL.md62 linessingle file
Debug and Fix Skill
Purpose
Find and fix the actual root cause of a bug with the smallest correct change — without masking symptoms, guessing, or introducing new risks.
When to Use
An error, crash, test failure, build failure, or lint failure occurs.
Behavior doesn't match expectations (UI shows wrong data, action doesn't do what it should, etc.).
A previous fix didn't fully resolve the issue.
When Not to Use
The "bug" is actually a missing feature/requirement, not broken existing behavior — use Plan the Feature Skill instead.
The issue is purely about code quality/structure with no broken behavior — use Refactor and Clean Up Skill.
Required Inputs
The actual error message/stack trace, failing test output, or a precise description of the unexpected behavior (steps to reproduce, expected vs. actual).
Access to the relevant code and recent changes (diff/history if available).
Assumptions
The reported symptom may not be where the actual root cause lives.
A fix is not correct just because the symptom disappears — it must address the actual cause.
Step-by-Step Workflow
Read the actual error message/stack trace in full — identify the exact file, line, and error type. Don't skip to guessing based on the general area.
Reproduce or confirm the issue: understand the exact steps/conditions that trigger it.
Trace the relevant code path: follow the logic from where the error surfaces back to where the bad state/input originates. Check function inputs, types, data shapes, and recent changes along this path.
Check recent changes (git history/diff if available) for anything that could have introduced this — especially if the bug is newly reported.
Form a hypothesis about the root cause, and verify it (e.g. by inspecting the actual data/state at the relevant point, not just assuming).
Identify the smallest correct fix that addresses the root cause — not a workaround that papers over it.
Apply the fix, following Write Front-End Code / Database and Backend Logic / etc. conventions as relevant to where the fix lives.
Validate the fix: confirm the original issue is resolved (re-run the failing test/reproduce steps) and run relevant validation (see Validate and Test Skill) to confirm nothing else broke.
If the root cause can't be confirmed: state clearly what was checked, what hypotheses were ruled out, and what remains unknown — don't apply a speculative fix and call it done.
Rules and Best Practices
Always read the actual error/log output before forming a hypothesis.
Trace the code path; don't fix based on the error message's surface location alone if the root cause is upstream.
Apply the smallest correct fix — avoid rewriting large sections "while you're in there."
Don't use any/as any, empty catch blocks, broad fallbacks, duplicated logic, or config hacks to make an error go away unless the root cause genuinely requires that specific change (and even then, document why).
If multiple bugs are found, fix the one that's actually in scope; note others separately rather than silently expanding scope.
After fixing, consider whether the same root cause affects other similar code paths (but don't change them speculatively without checking).