Agent skill · software engineering · sickn33
phase-gated-debugging
Use when debugging any bug. Enforces a 5-phase protocol where code edits are blocked until root cause is confirmed. Prevents premature fix attempts.
Why this skill is useful
Adds a structured debugging protocol that the AI wouldn't reliably generate on its own, ensuring disciplined root cause analysis before code changes.
What it needs
About 2k tokens when loaded. Last updated 2026-08-07. 44,571 stars on the source repository.
What this skill does
Phase-Gated Debugging Overview AI coding agents see an error and immediately edit code. They guess at fixes, get it wrong, and spiral. This skill enforces a strict 5-phase protocol where you CANNOT edit source code until the root cause is identified and confirmed. Based on claude-debug (full plugin with PreToolUse hook enforcement). When to Use Use this skill when: a bug keeps getting "fixed" without resolving the underlying issue you need to slow an agent down and force disciplined debugging before code edits the failure is intermittent, a regression, performance-related, or otherwise hard to isolate you want an explicit user confirmation checkpoint before any fix is applied The Protocol Phase 1: REPRODUCE Run the failing command/test. Capture the exact error. Run 2-3 times for consistency. Do NOT read source code Do NOT hypothesize Do NOT edit any files Phase 2: ISOLATE Read code. Add diagnostic logging marked // DEBUG. Re-run with diagnostics. Binary search to narrow down. Only // DEBUG marked logging is allowed Do NOT fix the bug even if you see it Phase 3: ROOT CAUSE Analyze WHY at the isolated location. Use "5 Whys" technique. Remove debug logging. State: "This is my root cause analysis: [explanation]. Do you agree, or should I investigate further?" WAIT for user confirmation. Do NOT proceed without it. Phase 4: FIX Remove all // DEBUG lines. Apply minimal change addressing confirmed root cause. Only edit files related to root cause Do NOT refactor unrelated code Phase 5: VERIFY Run original failing test — must pass. Run related tests. For intermittent bugs, run 5+ times. If verification fails: root cause was wrong, go back to Phase 2. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills sickn33/phase-gated-debugging