phase-gated-debugging
Lets your agent debug code using a safe protocol. It blocks edits until the root cause is confirmed, preventing rushed fixes.
What it does
This AI assistant helps fix bugs in your code in an organized way. It ensures the real problem is found before any changes are made, following a 5-step process to prevent rushed fixes.
When to use it
- ✓When a bug seems fixed but keeps coming back.
- ✓When you need a step-by-step process to find the cause of an error.
- ✓When the error happens occasionally and is hard to track down.
Example of what to ask your AI
“A bug is appearing in my code and I can't figure out the cause. Can you help me investigate using an organized process?”
Want more? Open the sections below.
How to use
The easiest way: copy the message below and paste it into Claude, ChatGPT, Cursor or any AI. It reads the skill and follows the instructions.
Skill link
Ready-to-paste message
How it works
The AI first tries to reproduce the error, then adds notes to understand where the problem occurs, analyzes the root cause, and only then applies a fix. Finally, it checks if the error is truly resolved.
Installation
Easiest way: copy the skill link and paste it into Claude, ChatGPT or Cursor asking it to follow the instructions.
In the terminal (Claude Code, Codex, Cursor), in your project folder:
npx skills add sickn33/agentic-awesome-skills --skill phase-gated-debuggingOr download just the file:
curl -L https://raw.githubusercontent.com/sickn33/agentic-awesome-skills/main/plugins/agentic-awesome-skills-claude/skills/phase-gated-debugging/SKILL.md -o SKILL.mdTechnical content (original SKILL.md)
Original text by the author, straight from GitHub.
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
// DEBUGmarked 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
- NEVER edit source code in phases 1-3 (except
// DEBUGin phase 2) - NEVER proceed past phase 3 without user confirmation
- ALWAYS reproduce before investigating
- ALWAYS verify after fixing
Example
User request:
a bug keeps getting "fixed" without resolving the underlying issue; diagnose it and return the concrete next action.
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.
FAQ
Why can't I edit the code immediately?
Editing code without understanding the root cause can worsen the problem or create new bugs. This process ensures the fix targets the source of the issue.
What are the 5 phases?
They are: 1. Reproduce the error, 2. Isolate the problem with notes, 3. Identify the root cause, 4. Apply the fix, and 5. Verify the error is resolved.
What happens if the fix doesn't work?
If the error isn't resolved during the verification phase, the AI goes back to the isolation phase to investigate again.
Details
Original description by the author
Use when debugging any bug. Enforces a 5-phase protocol where code edits are blocked until root cause is confirmed. Prevents premature fix attempts.
Popularity
- GitHub stars
- 48k
- Ranking position
- #3824
- License
- MIT
- Updated
- 10/15/2026
Comments
- …
More skills from this repository
00-andruia-consultant
Helps your agent start or improve AI projects. It analyzes code, suggests tools, and creates action plans in Spanish.
sickn33/agentic-awesome-skills
007
Lets your agent perform security audits and threat modeling. It's useful for protecting projects against attacks and vulnerabilities.
sickn33/agentic-awesome-skills
10-andruia-skill-smith
Helps your agent create or improve AI tools. It defines how tools work, writes documentation, and validates the structure.
sickn33/agentic-awesome-skills
20-andruia-niche-intelligence
Lets your agent create a summary about a specific industry. It's useful for understanding the context, rules, usage patterns, and risks of a project, using reliable sources.
sickn33/agentic-awesome-skills
Similar skills
benchmark-optimization-loop
Has your agent improve something's speed in a measured way. It tests multiple versions and chooses the fastest one that still works correctly.
affaan-m/ECC
change-impact
Helps your agent analyze the impact of code changes before making them. It compares the planned vs. actual results afterward, covering paths, data, tests, and documentation. Useful for risky or system-wide changes.
affaan-m/ECC
click-path-audit
Lets your agent trace all user buttons and interactions to find bugs. It finds issues where functions seem to work alone but fail together. Useful when bugs persist even after debugging.
affaan-m/ECC