Skip to content
Skills Library
Programming · Review & audit

bug-fix-protocol

/bug-fix-protocol

8-step disciplined bug-fix protocol that treats every production bug as two failures — the code defect itself and the testing system that allowed it through. Use when fixing a production bug, investigating a regression, writing a post-mortem, or auditing a missed defect. Triggers on "fix this bug", "production bug", "regression test", "post-mortem", "test gap", "why did the tests miss this".

Licence
MIT
Last repository change
24.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 24.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

8-step disciplined bug-fix protocol that treats every production bug as two failures — the code defect itself and the testing system that allowed it through. Use when fixing a production bug, investigating a regression, writing a post-mortem, or auditing a missed defect. Triggers on "fix this bug", "production bug", "regression test", "post-mortem", "test gap", "why did the tests miss this".

Triggers from the description

fix this bugproduction bugregression testpost-mortemtest gapwhy did the tests miss this
Original author description

8-step disciplined bug-fix protocol that treats every production bug as two failures — the code defect itself and the testing system that allowed it through. Use when fixing a production bug, investigating a regression, writing a post-mortem, or auditing a missed defect. Triggers on "fix this bug", "production bug", "regression test", "post-mortem", "test gap", "why did the tests miss this".

How it works

  1. When to apply
  2. The eight steps (summary)
  3. Output expectations
  4. Reference
Original SKILL.md headings · 36 lines, 347 words
SKILL.md preview
---
name: bug-fix-protocol
description: 8-step disciplined bug-fix protocol that treats every production bug as two failures — the code defect itself and the testing system that allowed it through. Use when fixing a production bug, investigating a regression, writing a post-mortem, or auditing a missed defect. Triggers on "fix this bug", "production bug", "regression test", "post-mortem", "test gap", "why did the tests miss this".
---

# Bug 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`](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)

1. **Analyze and reproduce requirements.** Understand exact actual vs expected behaviour; identify minimal repro path; ask the user before guessing on ambiguities.
2. **Write a failing test (red).** Encode the bug as a test that fails for the right reason. No code change yet.
3. **Trace root cause.** Walk the failing test back through the system. Stop at the smallest place that, if changed, makes the test pass.
4. **Apply the minimal fix.** Smallest possible change. No drive-by refactors.
5. **Verify green locally.** Failing test now passes; no other tests regressed.
6. **Run the full suite + lints + types.** Catch indirect regressions.
7. **Document the fix.** Commit message and PR description name the symptom, the root cause, and the fix in one sentence each.
8. **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`](PROTOCOL.md).
Files in this package (2)
  • PROTOCOL.md 7 KB
  • SKILL.md 3 KB

Versions

RepositoryScoreLicence
This page · CodeAlive-AI/ai-driven-development100MIT
nimadorostkar/Claude-Skills-collection100MIT

Database snapshot: 13.11.2026 · package version 03cdec9233d1 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100bug-fix
    Bug fix workflow. Use when: fixing bugs, resolving issues, regression fixes. Not for: new features (use feature-dev), understanding code (use code-explore). Output: fix + regression test + review gate.
  • 100post-mortem
    Trace when a bug was introduced, find the root cause commit, understand why it happened, and produce a structured post-mortem report. Use when the user says "post-mortem", "trace this bug", "when was this regression introduced", "find the root cause commit", "what commit broke…
  • 100hatch3r-bug-fix
    Step-by-step bug fix workflow. Diagnose root cause, implement minimal fix, write regression test. Use when fixing bugs, working on bug report issues, or when the user mentions a bug.
  • 90verify-fix
    WAY 9 — verify that a bug is fixed by running its regression test. Use when the user says "verify it", "verify fix", "is #142 fixed", "check the fix" with one or more bug refs (#142, SHOP-142), or "verify all" for every open bug that has a regression test.
  • 100diagnose
    Trace a bug, regression, failure, or crash to an evidence-backed root cause, then hand off or apply the minimal fix. Use when the cause is unknown or disputed, or when auditing where the same defect recurs.
  • 100diagnose
    Trace a bug, regression, failure, or crash to an evidence-backed root cause, then hand off or apply the minimal fix. Use when the cause is unknown or disputed, or when auditing where the same defect recurs.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.