Skip to content
Skills Library
Programming · Testing

fix-bug

/fix-bug

Use when a ticket reports defective behaviour — a wrong result, a crash, a regression, "X doesn't work when Y" — and the fix must be proven with a test that fails before and passes after. Invoke for any bug, incident follow-up, or "this used to work" ticket before touching the code.

Repository
gaffer ↗
Licence
Apache-2.0
Last repository change
29.09.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 29.09.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Use when a ticket reports defective behaviour — a wrong result, a crash, a regression, "X doesn't work when Y" — and the fix must be proven with a test that fails before and passes after. Invoke for any bug, incident follow-up, or "this used to work" ticket before touching the code.

Triggers from the description

X doesnthis used to work
Original author description

Use when a ticket reports defective behaviour — a wrong result, a crash, a regression, "X doesn't work when Y" — and the fix must be proven with a test that fails before and passes after. Invoke for any bug, incident follow-up, or "this used to work" ticket before touching the code.

How it works

  1. Steps
  2. Done when
  3. Stop and escalate when
  4. Rules
  5. Capture lore
Original SKILL.md headings · 88 lines, 941 words
SKILL.md preview
---
name: fix-bug
description: Use when a ticket reports defective behaviour — a wrong result, a crash, a regression, "X doesn't work when Y" — and the fix must be proven with a test that fails before and passes after. Invoke for any bug, incident follow-up, or "this used to work" ticket before touching the code.
stack: []
area: workflow
---

# Fix a bug — reproduce, isolate, fix the cause, guard

A bug fix is a claim: "this behaviour was wrong, and now it is right." The only proof a
reviewer can check is a test that fails on the old code for the reported reason and
passes on the new. Debugging is a search, so run it like an experiment: one hypothesis,
one change, one observation at a time.

## Steps

1. **Extract the facts; distrust the diagnosis.** From `get_ticket`, write down the input,
   the expected result, the actual result, the environment, and how often it happens. The
   reporter's theory of the cause is a hint, not a conclusion. Call `search_lore` for known
   gotchas in this area — many bugs are a documented gotcha resurfacing.
2. **Reproduce it before changing anything.** Drive the failing path with a scratch test
   or a command until you SEE the wrong behaviour. Then shrink the reproduction: remove
   inputs, steps and setup until removing one more makes the bug disappear. A minimal
   reproduction usually points straight at the cause.
   - **Intermittent / "sometimes loses data" / "500 under load":** assume shared state.
     Reproduce deterministically — fire two concurrent calls at the same resource (a
     barrier or `Promise.all`), fix the clock with a fake timer, or pause one party past a
     timeout (a lock holder that stalls past its lease). Guessing at a race is not a fix.
   - **"This used to work":** find the introducing commit with
     `git bisect start <bad> <good>` then `git bisect run <test command>` (keep the
     reproduction script untracked inside the worktree, never outside it — the hook
     blocks writes there; untracked files survive each bisect checkout — and delete
     it before your `git add -A` commit, or it ships in the diff).
     Always finish with `git bisect reset` and check `git branch --show-current` is the
     delivery branch again — the runner fails a delivery left on any other HEAD. The
     introducing diff names the cause.
3. **Write the regression test first.** Encode the minimal reproduction as a permanent
   test at the lowest level that exposes it (unit for a function, integration if it needs
   the wiring). Name it after the behaviour, not the ticket number. Run it and confirm it
   FAILS **for the reported reason** — the assertion about the wrong result, not an import
   error, a missing fixture, or a timeout. Keep that output; it is half your evidence.
4. **Find the cause, not the symptom.** Trace from the failing assertion back to the
   decision the code got wrong: a missing guard, an off-by-one boundary, an unhandled
   state, a non-atomic read-modify-write, a stale assumption about an API. Form one
   hypothesis, change one thing, re-run. If a change does not move the result, revert it
   before trying the next — stacked speculative edits hide the real fix.
5. **Fix minimally.** Change only what the cause requires (the `minimalism` skill). A
   `try/catch` that hides the error, a special case for the reporter's exact input, or a
   retry around a race is a symptom patch, not a fix.
6. **Look for siblings.** `grep` for the same call, the same boundary arithmetic, the same
   unguarded shared write. Fix identical instances only if they are the same bug; list the
   others as findings in your evidence rather than widening this diff.
7. **Prove it.** Run the regression test (now passes), then the surrounding suite and
   lint once. For a concurrency or timing bug, run the new test in a loop
   (`for i in {1..20}; do <cmd> || break; done`) — a single green run proves nothing
   about a race.
8. **Guard the class.** If a type, assertion, or validation would have made this bug
   impossible, add it when it is small and in the same code.

## Done when

- The regression test failed before the fix for the reported reason and passes after —
  both outputs recorded via the `record-evidence` skill (`test_output`), with a one-line
  statement of the cause. On a resume, where that call is refused, put them in your final
  message instead (see `record-evidence`).
- The suite and lint pass; siblings are fixed or listed.

## Stop and escalate when

- You cannot reproduce after trying the reported inputs plus two deliberate variations
  (environment, data, timing). Record what you tried and call `request_decision`
  (`human_required`) naming the exact artefact you need — a payload, a log line, a
  version — then `mark_ticket_blocked` (refused on a resume, where the decision only stops
  the ticket being claimed again — the runner still submits what you committed, so
  commit no speculative fix). A blind fix of an unreproduced bug is a second bug.
- The real fix needs a schema change, a new dependency, or a behaviour change the ticket
  did not ask for: `request_decision` with the options.

## Rules

- No fix without a reproduction; no reproduction without a permanent test.
- Never delete, skip, or loosen a failing test to make the bug "go away".
- One bug per ticket; siblings become findings, not scope creep.
- Work on the delivery branch the runner prepared (the `create-branch` skill verifies);
  commit, never push.

## Capture lore

This skill is one of the places durable, reusable knowledge naturally surfaces:
**While reproducing a defect you find the assumption the code made and the input that broke it — an API quirk, a boundary the code assumed away, a library behaviour nobody wrote down.** That kind of fact is *lore*. Capture it via the **lore-capture
protocol in your brief** (`CLAUDE.factory.md`, step 11 "Memory contribution"):
call the Memory MCP `suggest_lore` once at the close of your work — reusable
conventions, gotchas, decisions, and boundaries only, never per-ticket trivia.

Versions

RepositoryScoreLicence
This page · tmj-90/gaffer100Apache-2.0
mthines/agent-skills100MIT
mgiovani/cc-arsenal100MIT
tddworks/claudebar100Apache-2.0
bytebase/dbhub100MIT
remix-run/react-router100MIT
Cynnamoroll/factory-stack100MIT
nowsprinting/unity-coding-skills100Unlicense
Slama-Consulting/proofbench100MIT

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

  • 100regression-tests
    Pin every fixed bug with a test that fails before the fix and passes after, kept beside the code it guards. Use when closing a bug so the same defect cannot return silently through a later refactor or merge.
  • 100regression-proof
    Fix a reported bug with a regression test that demonstrably fails on the original behavior and passes after the fix. Use when implementing a bug fix or checking whether a proposed fix actually addresses a reported failure. Not a general coverage audit or new-feature workflow.
  • 100tdd
    Make a bug in a TypeScript resource executable before fixing it, with a regression test that fails before the fix and passes after. Use only when the user asks for TDD, a failing test, or a regression test, or when the resource already has a test runner and the bug has an…
  • 90qa-regression
    Run /qa-regression to lock a verified fix in place with a regression test. Use it after /qa-verify proves the fix. It writes the test that fails on the pre-fix tree and passes on the fix, prefers the tagged BDD scenario as its source, quarantines flakes instead of retrying them,…
  • 100trove-tdd
    Write a focused regression test that fails before the fix and passes after. Use when the user asks for TDD, a failing test, or a regression test, or when a bug has a cheap local test target. Skip when the test path is expensive, integration-heavy, or unclear.
  • 90fix-flaky-test
    Use when a ticket reports an intermittently failing test — passes sometimes, fails others, or fails in CI but not locally. Invoke for "this test is flaky", "fix the intermittent failure in X", or "the suite is non-deterministic". Fix the root cause — in the test or in the…

Feedback and reports

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