Skip to content
Skills Library
Programming · Testing

bug-fix-protocol

/bug-fix-protocol

Use when fixing a reported bug end to end. Enforces a disciplined sequence — reproduce, write a failing test, fix minimally, verify, prevent recurrence — and blocks the common failure mode of patching symptoms. Trigger on "fix this bug", "users are reporting that", "this regressed in the last release", "need a hotfix for". Do not use when the cause is still unknown — see the debugging skill.

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
1
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

Use when fixing a reported bug end to end. Enforces a disciplined sequence — reproduce, write a failing test, fix minimally, verify, prevent recurrence — and blocks the common failure mode of patching symptoms. Trigger on "fix this bug", "users are reporting that", "this regressed in the last release", "need a hotfix for". Do not use when the cause is still unknown — see the debugging skill.

Triggers from the description

fix this bugusers are reporting thatthis regressed in the last releaseneed a hotfix for
Original author description

Use when fixing a reported bug end to end. Enforces a disciplined sequence — reproduce, write a failing test, fix minimally, verify, prevent recurrence — and blocks the common failure mode of patching symptoms. Trigger on "fix this bug", "users are reporting that", "this regressed in the last release", "need a hotfix for". Do not use when the cause is still unknown — see the debugging skill.

How it works

  1. Purpose
  2. When to Use
  3. Capabilities
  4. Inputs
  5. Outputs
  6. Workflow
  7. Best Practices
  8. Examples
  9. Notes
Original SKILL.md headings · 80 lines, 585 words
SKILL.md preview
---
name: bug-fix-protocol
description: Use when fixing a reported bug end to end. Enforces a disciplined sequence — reproduce, write a failing test, fix minimally, verify, prevent recurrence — and blocks the common failure mode of patching symptoms. Trigger on "fix this bug", "users are reporting that", "this regressed in the last release", "need a hotfix for". Do not use when the cause is still unknown — see the debugging skill.
metadata:
  category: development
  version: 1.0.0
  tags: [bugfix, testing, root-cause, process]
---

# Bug Fix Protocol

## Purpose

Turn a bug report into a merged fix without introducing a second bug. The protocol is deliberately rigid: it exists to prevent the two most common failures — fixing the symptom, and fixing the cause without proving it.

## When to Use

- Any reported defect with a reproducible symptom.
- A regression discovered in CI or production.
- A hotfix under time pressure — especially then.

## Capabilities

- Reproduction and minimization.
- Root-cause isolation (see the `debugging` skill for the search method).
- Minimal, targeted fixes with regression tests.
- Blast-radius assessment for the same class of defect elsewhere.

## Inputs

- The bug report: expected behavior, observed behavior, environment, steps.
- Access to logs, traces, or a failing build.
- The severity and whether a rollback is available.

## Outputs

- A failing test that captures the bug.
- The smallest change that makes it pass.
- A note on where else this defect class could occur.

## Workflow

1. **Reproduce before reading code.** If you cannot reproduce it, the report is incomplete — go back for the missing detail. Do not guess.
2. **Write the failing test.** In the real test suite, at the right level. It must fail for the right reason, with a clear message.
3. **Find the cause.** Not the line where it crashed — the decision that made the crash possible.
4. **Fix minimally.** Change only what is required. Refactoring belongs in a separate commit.
5. **Verify.** New test passes; full suite passes; reproduce the original scenario manually and confirm it is gone.
6. **Look for siblings.** Grep for the same pattern elsewhere. A bug found once is usually present three times.
7. **Close the loop.** State in the PR: what broke, why, what changed, and what now prevents it.

## Best Practices

- If you cannot write a test that fails before the fix, you have not understood the bug.
- Under time pressure, mitigate first (rollback, feature flag, rate limit), then fix properly. Do not ship a rushed fix to production and call it done.
- Never "fix" a flaky test by retrying it. Flakiness is a real defect in the test or the code.
- Do not widen a `try/except` to make an error go away. That hides the next bug too.
- Record the root cause in the issue, not just the fix. The next person will search for the symptom.

## Examples

**PR description that closes the loop:**

```markdown
## What broke
Users on annual plans were charged twice when upgrading mid-cycle.

## Why
`ProrationCalculator` issued the invoice before checking whether the
subscription already had a pending invoice for the same period. Under
concurrent upgrade requests, both passed the check.

## Fix
Added a unique constraint on (subscription_id, period_start) and made
invoice creation idempotent on that key. The second request now returns
the existing invoice rather than creating one.

## Prevention
Regression test `test_concurrent_upgrade_creates_one_invoice` runs two
upgrades in parallel and asserts a single invoice. Audited the other
three call sites of `issue_invoice` — `RenewalJob` had the same gap and
is fixed in the same commit.
```

## Notes

- Idempotency keys on write endpoints prevent an entire class of duplicate-side-effect bugs. If the bug was a duplicate charge, message, or record, this is usually the real fix.
- If a bug is reported and cannot be reproduced after honest effort, close it as such and say what you tried. Leaving it open forever is not diligence.

Versions

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

Database snapshot: 13.11.2026 · package version 8c764aa6f12a (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

  • 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.
  • 100acp-bug-fix
    Use when the user asks to fix a bug, investigate an error, debug a crash, explain a stack trace, or make a failing test pass. Enforces reproduce → isolate → smallest fix → verify, instead of guessing a cause and patching code.
  • 100fix-issue
    Workflow for fixing a reported bug in the Patrol monorepo — reproduce, locate the right package, fix without regressions, verify, and open a PR. Use when asked to fix a GitHub issue (e.g. "fix issue #3101"), investigate a reported Patrol bug, or turn a bug report into a tested PR.
  • 100bug-fix
    Drive the teeth-gated lifecycle for reported defects: diagnose root cause, prove it, and prevent regression through REPORTED → DIAGNOSING → ROOT_CAUSED → FIXING → REVIEWED → DONE, with VERIFIED, ESCALATED, and RESOLVED_ON_MAIN paths where needed. Auto-fires on fix this bug,…
  • 100bug-fix
    Drive the teeth-gated lifecycle for reported defects: diagnose root cause, prove it, and prevent regression through REPORTED → DIAGNOSING → ROOT_CAUSED → FIXING → REVIEWED → DONE, with VERIFIED, ESCALATED, and RESOLVED_ON_MAIN paths where needed. Auto-fires on fix this bug,…
  • 100systematic-debugging
    Four-phase debugging protocol (reproduce, investigate, root-cause, fix) that prevents guess-and-fix thrashing. Use this skill whenever a test fails, a bug is reported, an error occurs during implementation, or any unexpected behavior is encountered. Prevents the common LLM…

Feedback and reports

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