Skip to content
Skills Library
Programming · Testing

bugfix

/bugfix

Use when a bug is reported, something is broken, an error or crash needs fixing, a wrong output appears, or a regression shows up — guides Grimoire's Reproduce → Root-Cause → failing-test-FIRST → Fix → Verify discipline and will not let the fix begin until a failing regression test is recorded. Use also when the user says "bugfix", "/bugfix", "fix this bug", or "something is broken".

Repository
grimoire ↗
Licence
Apache-2.0
Last repository change
23.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 23.10.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 bug is reported, something is broken, an error or crash needs fixing, a wrong output appears, or a regression shows up — guides Grimoire's Reproduce → Root-Cause → failing-test-FIRST → Fix → Verify discipline and will not let the fix begin until a failing regression test is recorded. Use also when the user says "bugfix", "/bugfix", "fix this bug", or "something is broken".

Triggers from the description

bugfixfix this bugsomething is broken

Arguments

/bugfix [bug report / repro steps / issue number]
Original author description

Use when a bug is reported, something is broken, an error or crash needs fixing, a wrong output appears, or a regression shows up — guides Grimoire's Reproduce → Root-Cause → failing-test-FIRST → Fix → Verify discipline and will not let the fix begin until a failing regression test is recorded. Use also when the user says "bugfix", "/bugfix", "fix this bug", or "something is broken".

How it works

  1. The non-negotiable sequence
  2. Phase 1 — Reproduce (no guessing)
  3. Phase 2 — Root-Cause Analysis (write it down)
  4. Phase 3 — Failing test FIRST 🚧 GATE
  5. Phase 4 — Fix (minimal, root-cause)
  6. Phase 5 — Verify (evidence, not vibes)
  7. Phase 6 — Review-Fix Loop (+ optional Codex)
  8. Phase 7 — Commit
  9. Anti-rationalizations (stop if you think these)
  10. References
Original SKILL.md headings · 115 lines, 880 words
SKILL.md preview
---
name: bugfix
description: Use when a bug is reported, something is broken, an error or crash needs fixing, a wrong output appears, or a regression shows up — guides Grimoire's Reproduce → Root-Cause → failing-test-FIRST → Fix → Verify discipline and will not let the fix begin until a failing regression test is recorded. Use also when the user says "bugfix", "/bugfix", "fix this bug", or "something is broken".
user-invocable: true
argument-hint: "[bug report / repro steps / issue number]"
triggers:
  - "fix a bug"
  - "bug fix"
  - "something is broken"
  - "regression test first"
  - "reproduce the bug"
---

# /bugfix — Guided Bug-Fix Workflow

Guard rail for the #1 bug-fix failure: **fixing before a failing test exists.**
This skill walks [`workflow-bugfix.md`](../../rules/workflow-bugfix.md) (the
single source of truth) and adds one hard, non-skippable gate — **Phase 3 must
produce a test that fails on the current code before any fix is written.**

> Why this exists: the rule alone was repeatedly skipped. This skill makes the
> order explicit and the gate blocking. Read `workflow-bugfix.md` for the full
> rationale; this file is the executable checklist.

## The non-negotiable sequence

```
Reproduce → Root-Cause Analysis → FAILING TEST → Fix → Verify → Review → Commit
```

Each phase finishes before the next starts. The **only** way past Phase 3 is a
test that you have **run** and **watched fail** for the right reason.

## Phase 1 — Reproduce (no guessing)

- State the exact wrong behavior: command, input, observed vs expected.
- Find the surface: which entry point(s)? CLI command, TUI path, library seam?
  A bug often lives on more than one surface (e.g. a CLI path AND its TUI twin);
  list every one that shares the broken code.
- Confirm it actually reproduces. If you can't reproduce it, keep digging —
  **no speculative fixes.**

Write a one-line repro: `"<cmd/inputs> → <observed>; expected <expected>"`.

## Phase 2 — Root-Cause Analysis (write it down)

- Trace the symptom to the line **and** the condition that made it fire.
- Output a root-cause statement in this exact shape — no "error on line N":

  > **X happens because Y, introduced by/located at Z.**

- Single bug or a pattern? Grep for the same defect elsewhere (sibling call
  sites, the other surface from Phase 1). If it's a pattern, the fix covers all
  instances.
- If the real cause needs an architectural change, stop and escalate to the
  feature workflow with a plan artifact — don't paper over it.

## Phase 3 — Failing test FIRST 🚧 GATE

**Do not edit any production code until this phase is done.**

1. Write the test that exercises the Phase-1 repro and targets the Phase-2 root
   cause (not just the symptom).
   - Acceptance-level → `test/tests/test_*.py` (real binary + registry).
   - Unit-level → inline `#[cfg(test)]` in the affected module.
2. **Run it. Paste the red output.** It must fail, and fail for the *bug's*
   reason (assertion on the wrong behavior) — not a compile error, typo, or
   missing fixture.
3. If an **existing** test encodes the buggy behavior (it asserts the wrong
   thing the user is now reporting), that test is part of the bug — note it; it
   will be corrected in the fix, with the reason recorded.

**Gate to pass Phase 3 — all three true:**
- [ ] A test exists that exercises the repro.
- [ ] You ran it and it **failed** (output shown).
- [ ] The failure is the bug, not test scaffolding.

If you cannot make a test fail, you have not reproduced or understood the bug —
return to Phase 1/2. Skipping this gate is the failure mode this skill prevents.

## Phase 4 — Fix (minimal, root-cause)

- Smallest change that addresses the Phase-2 cause. No drive-by refactor, no
  "while I'm here" cleanup (separate commit, separate type).
- Fix **every** instance the Phase-2 pattern search found.
- Correct any existing test that encoded the wrong behavior — state *why* in the
  diff/commit (user intent / corrected contract supersedes the old assumption).

## Phase 5 — Verify (evidence, not vibes)

- The Phase-3 test now **passes** (show it).
- Run the **subsystem** gate for the changed area (e.g. `task rust:verify`),
  then cache-bust + re-run unit tests if Rust (`touch` the edited files so a
  stale cache can't mask a failure).
- Manually confirm the Phase-1 repro no longer reproduces.
- Final gate before commit: `task --force verify` (fmt + clippy + build + unit +
  acceptance). Verify it yourself — do not trust "should pass".

## Phase 6 — Review-Fix Loop (+ optional Codex)

Apply the canonical Review-Fix Loop from `workflow-bugfix.md` (correctness vs
root cause, regression risk to other callers, minimality, test adequacy). For a
non-trivial fix, run one Codex adversarial pass over the diff as the cross-model
gate; fix real findings, re-verify, then converge.

## Phase 7 — Commit

- `fix:` conventional commit; body names the root cause and the regression test.
- Reference the issue (`fixes #N`) when one exists.
- Never push — the human decides (see [`workflow-git.md`](../../rules/workflow-git.md)).

## Anti-rationalizations (stop if you think these)

| Thought | Reality | Do this |
|---|---|---|
| "I know the cause, I'll just fix it." | No Phase-2 statement written. | Write the root-cause line first. |
| "The test is trivial, I'll add it after." | A test added after the fix never proved it caught the bug. | Write it first, watch it fail. |
| "Existing tests cover this area." | They may encode the *buggy* behavior. | Add a test for the *exact* broken path. |
| "Clippy/format nit nearby, I'll fix too." | Scope creep. | Separate `chore:`/`refactor:` commit. |

## References

- [`workflow-bugfix.md`](../../rules/workflow-bugfix.md) — full workflow + gates (source of truth)
- [`workflow-intent.md`](../../rules/workflow-intent.md) — work-type routing
- [`quality-core.md`](../../rules/quality-core.md) — verification honesty, review checklist
- [`workflow-git.md`](../../rules/workflow-git.md) — `fix:` commits, never push

Versions

RepositoryScoreLicence
This page · grimoire-rs/grimoire100Apache-2.0
qwenlm/qwen-code100Apache-2.0
marian-kamenistak/sap-ai-skills100MIT
duthaho/skillhub100MIT
alibaba/mnn95Apache-2.0
4typen/skills90MIT
kangig94/coral90MIT
woliveiras/baseline86MIT

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

  • 100kickstart-bugfix
    Disciplined bug fixing in three recorded steps: assess (reproduce, find the root cause, judge severity and security impact), fix (failing regression test first, then the smallest change that makes it pass) and verify (re-run the original reproduction and the full suite, ending…
  • 90bug-fixing-openclaw
    Zero-regression bug fix workflow: triage → reproduce → root cause → impact analysis → fix → verify → knowledge deposit → self-reflect. Use when: - Feature broken, incorrect behavior, wrong output, errors/exceptions - Console errors/warnings even when feature appears functional -…
  • 90pm-bugfix
    Create or manage a bug-fix workflow packet. Use when the user reports a bug, says "fix this bug", or needs a structured workflow for diagnosing and resolving a defect. Emphasizes reproduction, root cause analysis, minimal fix, and regression testing.
  • 100bugfix-workflow
    End-to-end bugfix workflow. Test first, plan, fix, verify. Use when the user says "fix bug", "bugfix", "investigate issue", "fix #NNN", or any bug-related work. Covers reproduction, test creation, RCA, fix implementation, verification, and ticket documentation.
  • 100systematic-debugging
    Four-phase debugging - reproduce, isolate, root cause, fix behind a failing regression test; use for any bug or failure.
  • 95rs-bugfix
    Use when fixing a known or suspected bug — reproduce it with a failing test first, confirm independently, fix at the invariant (not the symptom), hunt the variants of the same root cause, prove the fix, and leave a regression guard and a reviewable report. Also for regressions…

Feedback and reports

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