What problem does Phase-Gated Debugging solve?

It prevents AI coding agents from immediately guessing at fixes when they encounter an error, which often leads to ineffective changes and debugging spirals. Instead, it enforces a strict 5-phase protocol that requires identifying and confirming the root cause before any code edits are made.

What are the five phases of the debugging protocol?

Phase 1 (REPRODUCE) runs the failing command 2-3 times to capture the exact error; Phase 2 (ISOLATE) adds diagnostic logging and uses binary search to narrow down the issue; Phase 3 (ROOT CAUSE) analyzes why the bug occurs using the 5 Whys technique and waits for your explicit confirmation; Phase 4 (FIX) applies a minimal change addressing only the confirmed root cause; Phase 5 (VERIFY) runs the original test and related tests to confirm the fix works.

When should I use Phase-Gated Debugging?

Use it when a bug keeps getting "fixed" without resolving the underlying issue, when you need disciplined debugging before code edits, or when dealing with intermittent bugs, regressions, performance issues, or other hard-to-isolate failures. Do not use it for tasks outside the debugging scope.

What is the mandatory confirmation checkpoint in this skill?

At Phase 3 (ROOT CAUSE), the agent waits for your explicit confirmation before proceeding to Phase 4. This ensures no code changes occur until you agree with the root cause analysis.

What bug-type-specific strategies does this skill include?

The skill includes stack trace backward tracing for crashes/panics, binary search with midpoint logging for wrong output, comparison of passing vs failing run logs for intermittent bugs, git bisect for regressions, and timing at stage boundaries for performance issues.

Skill

Enforce Disciplined Debugging Protocol

Name: Phase-Gated Debugging
Availability: OnlineOnly
Author: Antigravity

A 5-phase debugging protocol that blocks code edits until a bug's root cause is confirmed by the user first.

Get skill

Works with github

Antigravity

Own this? Claim it

Spark score

out of 100

Updated 20 days ago

Version 14.1.0

Add to Favorites

Why it matters

Prevent AI agents from making speculative code changes by enforcing a strict, multi-phase debugging protocol that requires root cause identification and user confirmation before any fixes are applied.

Outcomes

What it gets done

Reproduce and capture exact errors before any investigation.

Isolate bugs using diagnostic logging and binary search.

Perform root cause analysis with user confirmation.

Verify fixes against original failing tests.

Install

Add it to your toolbox

Run in your project directory:

curl -fsSL https://spark.entire.vc/get/ag-phase-gated-debugging | bash

Overview

Phase-Gated Debugging

A 5-phase debugging protocol (Reproduce, Isolate, Root Cause, Fix, Verify) that blocks source-code edits until the root cause is confirmed by the user, with technique matched to bug type. Use when a bug keeps getting misdiagnosed or re-broken, or when an agent needs an enforced checkpoint before editing code, especially for intermittent, regression, or performance bugs.

What it does

Phase-Gated Debugging enforces a strict 5-phase protocol that blocks an AI coding agent from editing source code until a bug's root cause is identified and confirmed, countering the instinct to see an error and immediately guess at a fix. It is based on the claude-debug plugin, which enforces the phases with a PreToolUse hook.

When to use - and when NOT to

Use this when a bug keeps getting "fixed" without resolving the underlying issue, when an agent needs to be slowed down into disciplined debugging before touching code, when the failure is intermittent, a regression, performance-related, or otherwise hard to isolate, or when an explicit user-confirmation checkpoint is wanted before any fix is applied.

Inputs and outputs

Five sequential phases: Reproduce (run the failing command or test, capture the exact error, repeat 2-3 times for consistency - no reading source, no hypothesizing, no editing files); Isolate (read code, add diagnostic logging marked // DEBUG, re-run with diagnostics, binary search to narrow the location - only // DEBUG-marked logging is allowed, and the bug must not be fixed even once spotted); Root Cause (analyze why at the isolated location using the "5 Whys" technique, remove debug logging, then state "This is my root cause analysis: [explanation]. Do you agree, or should I investigate further?" and wait for user confirmation before proceeding); Fix (remove all // DEBUG lines and apply the minimal change addressing the confirmed root cause, touching only files related to that cause and not refactoring unrelated code); and Verify (run the original failing test until it passes, run related tests, and for intermittent bugs run 5+ times - if verification fails, the root cause was wrong and the process returns to Phase 2).

Integrations

Matches technique to bug type: a crash or panic gets traced backward through the stack trace to where the bad value originated; wrong output gets a binary search, logging the midpoint and halving the search space each iteration; an intermittent bug gets compared passing-vs-failing run logs to find where they diverge; a regression gets git bisect to find the offending commit; and a performance issue gets timing measurements at stage boundaries to find the bottleneck.

Who it's for

Teams or agent workflows where debugging keeps looping on wrong fixes and need an enforced checkpoint. Four rules govern it throughout: never edit source code in phases 1-3 except for // DEBUG logging in phase 2, never proceed past phase 3 without user confirmation, always reproduce before investigating, and always verify after fixing.

FAQ

Common questions

Discussion