Phase gated debugging
Shared library of AI agent skills — works across Claude Code, Cursor, Codex, Windsurf, OpenCode, and Google Antigravity via a single universal installer.
npx -y skills add newmindsgroup/ai-agent-skills-library --skill phase-gated-debuggingAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
What its author says it does
Copied from the file, not written here
Use when debugging any bug. Enforces a 5-phase protocol where code edits are blocked until root cause is confirmed. Prevents premature fix attempts.
The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.
SKILL.md
3.1 KB, 626 tokens by cl100k_base, as published. Nobody here has run it
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
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.
What ships with it
Read from the repository
Just SKILL.md. No reference files, no scripts.