phase-gated-debugging

name	phase-gated-debugging
description	Use when debugging any bug. Enforces a 5-phase protocol where code edits are blocked until root cause is confirmed. Prevents premature fix attempts.
type	skill
created	2026-02-27T00:00:00.000Z
domain	productivity
category	developer-experience
risk	unknown
source	community
tags	["skill","productivity","developer-experience","phase","gated","debugging"]

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.

Bug-Type Strategies

Type	Technique
Crash/Panic	Stack trace backward — trace the bad value to its source
Wrong Output	Binary search — log midpoint, halve search space each iteration
Intermittent	Compare passing vs failing run logs — find ordering divergence
Regression