bug-fix-protocol skill
✓ VerifiedImplements an eight-step disciplined process to fix code defects and the testing systems that allowed them to pass through.
- GitHub stars
- 173
- Files
- 2
- Last commit
- Nov 11, 2026
- License
- MIT
- Allowed tools
- —
What does the bug-fix-protocol skill do?
bug-fix-protocol implements an eight-step disciplined process to fix code defects and the testing systems that allowed them to pass through.
Summary generated from the skill's SKILL.md.
About the bug-fix-protocol skill
Fixing production defects by addressing both the code error and the underlying testing failure is the primary function of this skill. Developers use it when investigating regressions, writing post-mortems, or auditing missed defects that reached staging or customer environments. It is designed to be triggered by specific phrases like "fix this bug" or "why did the tests miss this" to ensure a disciplined approach to software stability.
An agent loads this protocol to execute an eight-step workflow that begins with reproducing requirements and writing a failing test. The process moves through root cause tracing and applying minimal fixes before concluding with a mandatory audit of the testing system. Instead of just providing a code patch, the skill produces a reproduction test, the minimal code change, and a specific audit paragraph identifying the coverage gap that allowed the bug to pass through initially.
What an agent can do with it
- 1Resolve production defectsAn AI can follow a structured eight-step process to fix a bug that has reached a customer environment.
- 2Perform post-mortem analysisDevelopers can use the tool to investigate why a regression occurred and how to prevent similar issues.
- 3Strengthen testing infrastructureThe skill identifies which layer of the testing suite failed and implements a change to close that specific gap.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the bug-fix-protocol skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the bug-fix-protocol skill in Plugin
/plugin marketplace add CodeAlive-AI/ai-driven-development /plugin install ai-driven-development@ai-driven-development
Install the bug-fix-protocol skill in Claude Code
~/.claude/skills/bug-fix-protocol/SKILL.md
$ npx degit CodeAlive-AI/ai-driven-development/skills/bug-fix-protocol ~/.claude/skills/bug-fix-protocolInstall the bug-fix-protocol skill in Claude Code (project)
.claude/skills/bug-fix-protocol/SKILL.md
$ npx degit CodeAlive-AI/ai-driven-development/skills/bug-fix-protocol .claude/skills/bug-fix-protocolInstall the bug-fix-protocol skill in Codex
~/.agents/skills/bug-fix-protocol/SKILL.md
$ npx degit CodeAlive-AI/ai-driven-development/skills/bug-fix-protocol ~/.agents/skills/bug-fix-protocolInstall the bug-fix-protocol skill in Gemini CLI
~/.gemini/skills/bug-fix-protocol/SKILL.md
$ npx degit CodeAlive-AI/ai-driven-development/skills/bug-fix-protocol ~/.gemini/skills/bug-fix-protocolInstall the bug-fix-protocol skill in Claude.ai
npx degit CodeAlive-AI/ai-driven-development/skills/bug-fix-protocol bug-fix-protocol && zip -r bug-fix-protocol.zip bug-fix-protocol # claude.ai → Customize → Skills → + → Create skill → Upload a skill → bug-fix-protocol.zip
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work
- Source repository linked and reachablecodealive-ai/ai-driven-development/skills/bug-fix-protocol is public and reachablegithub.com/codealive-ai/ai-driven-development/tree/HEAD/skil ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit 2026-11-11github.com/codealive-ai/ai-driven-development/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/codealive-ai/ai-driven-development/blob/HEAD/skil ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/codealive-ai/ai-driven-development/blob/HEAD/skil ↗Pass
SKILL.md
View on GitHubBug Fix Protocol
A bug fix is two fixes in one: fix the code, and fix the testing system that let the bug through. Skipping the second step means the same class of bug ships again.
The full protocol (philosophy, eight steps with examples, audit checklist, anti-patterns) lives in PROTOCOL.md. Read it before applying.
When to apply
Use this protocol whenever a defect reaches production, staging, or a customer environment. Do not use it for bugs caught locally during normal development — those are part of the writing process, not testing-system failures.
The eight steps (summary)
- Analyze and reproduce requirements. Understand exact actual vs expected behaviour; identify minimal repro path; ask the user before guessing on ambiguities.
- Write a failing test (red). Encode the bug as a test that fails for the right reason. No code change yet.
- Trace root cause. Walk the failing test back through the system. Stop at the smallest place that, if changed, makes the test pass.
- Apply the minimal fix. Smallest possible change. No drive-by refactors.
- Verify green locally. Failing test now passes; no other tests regressed.
- Run the full suite + lints + types. Catch indirect regressions.
- Document the fix. Commit message and PR description name the symptom, the root cause, and the fix in one sentence each.
- Audit the testing system (the most important step). Ask: which layer should have caught this, and why didn't it? Then change that layer so it would catch the next instance — new test type, new fixture, new lint rule, new property test, new contract assertion. A fix without step 8 is incomplete.
Output expectations
When applying the protocol, return:
- The repro test (red, then green).
- The minimal code fix.
- A one-paragraph step-8 audit naming the missed coverage layer and the change made to close the gap.
If step 8 produces "we couldn't have caught this," investigate further — that answer is almost always wrong, and accepting it is how the testing system stagnates.
Reference
Full text: PROTOCOL.md.
Files in this skill
2bug-fix-protocol skill questions
How do I install the bug-fix-protocol skill in Claude Code?
Run npx degit CodeAlive-AI/ai-driven-development/skills/bug-fix-protocol ~/.claude/skills/bug-fix-protocol. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the bug-fix-protocol skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
When should I use this protocol?
Use this protocol when a defect reaches production, staging, or a customer environment, but not for bugs caught locally during normal development.
What are the expected outputs when applying this protocol?
The agent should provide the reproduction test (showing red then green), the minimal code fix, and a one-paragraph audit of the testing system.
Is fixing the code enough to complete the protocol?
No, a fix is considered incomplete unless you also audit and update the testing system to prevent similar bugs.