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.
Best use case
phase-gated-debugging is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Use when debugging any bug. Enforces a 5-phase protocol where code edits are blocked until root cause is confirmed. Prevents premature fix attempts.
Teams using phase-gated-debugging should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/phase-gated-debugging/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How phase-gated-debugging Compares
| Feature / Agent | phase-gated-debugging | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Use when debugging any bug. Enforces a 5-phase protocol where code edits are blocked until root cause is confirmed. Prevents premature fix attempts.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# 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](https://github.com/krabat-l/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 | `git bisect` — find the offending commit | | Performance | Timing at stage boundaries — find the bottleneck | ## Key Rules 1. NEVER edit source code in phases 1-3 (except `// DEBUG` in phase 2) 2. NEVER proceed past phase 3 without user confirmation 3. ALWAYS reproduce before investigating 4. ALWAYS verify after fixing ## Limitations - Use this skill only when the task clearly matches the scope described above. - Do not treat the output as a substitute for environment-specific validation, testing, or expert review. - Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
Related Skills
systematic-debugging
Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
error-debugging-multi-agent-review
Use when working with error debugging multi agent review
error-debugging-error-trace
You are an error tracking and observability expert specializing in implementing comprehensive error monitoring solutions. Set up error tracking systems, configure alerts, implement structured logging, and ensure teams can quickly identify and resolve production issues.
error-debugging-error-analysis
You are an expert error analysis specialist with deep expertise in debugging distributed systems, analyzing production incidents, and implementing comprehensive observability solutions.
distributed-debugging-debug-trace
You are a debugging expert specializing in setting up comprehensive debugging environments, distributed tracing, and diagnostic tools. Configure debugging workflows, implement tracing solutions, and establish troubleshooting practices for development and production environments.
debugging-toolkit-smart-debug
Use when working with debugging toolkit smart debug
debugging-strategies
Transform debugging from frustrating guesswork into systematic problem-solving with proven strategies, powerful tools, and methodical approaches.
find-skills
Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
vercel-cli-with-tokens
Deploy and manage projects on Vercel using token-based authentication. Use when working with Vercel CLI using access tokens rather than interactive login — e.g. "deploy to vercel", "set up vercel", "add environment variables to vercel".
vercel-react-view-transitions
Guide for implementing smooth, native-feeling animations using React's View Transition API (`<ViewTransition>` component, `addTransitionType`, and CSS view transition pseudo-elements). Use this skill whenever the user wants to add page transitions, animate route changes, create shared element animations, animate enter/exit of components, animate list reorder, implement directional (forward/back) navigation animations, or integrate view transitions in Next.js. Also use when the user mentions view transitions, `startViewTransition`, `ViewTransition`, transition types, or asks about animating between UI states in React without third-party animation libraries.
vercel-react-native-skills
React Native and Expo best practices for building performant mobile apps. Use when building React Native components, optimizing list performance, implementing animations, or working with native modules. Triggers on tasks involving React Native, Expo, mobile performance, or native platform APIs.
deploy-to-vercel
Deploy applications and websites to Vercel. Use when the user requests deployment actions like "deploy my app", "deploy and give me the link", "push this live", or "create a preview deployment".