/bugfix

← Back to index

Summary

You have a bug and need it gone — not just patched. Drives a four-agent pipeline: failing test first (code inspection doesn't count — only a red test does), TDD fix, doc update, full iterative-review loop, then commit. Every agent works from one core assumption: the bug is real and it exists — none may conclude "there is no bug" or "cannot reproduce, closing."

When to use

A bug is reported — from a user, a failing CI run, a bug-report file, or your own observation. Use /bugfix to drive the whole fix end-to-end: reproduce it with a test, fix the code, review the result, and commit — without losing your place in the investigation.

The argument is a bug description or a path to a bug-report file. If it resolves to a readable file, the skill reads it. If it's prose, it uses it verbatim. Empty argument → it asks you first.

Invocation

Free-text bug description:

/bugfix <description>

Path to a bug-report file:

/bugfix Documentation/Backlog/bug-xyz.md

The pipeline, in order:

  1. Reproduce — write a permanently placed failing test that fails for this bug. Code inspection is not acceptable proof.
  2. Fix (TDD) — make the smallest change to production code that turns the test green. The reproduction test is never touched.
  3. Update docs — sync any documentation that described the broken behaviour.
  4. Iterative review — runs /iterative-review until no Critical, Major, or Moderate issues remain.
  5. Commit — invokes /commit. If the commit is rejected (hook, nothing staged), the error is reported verbatim — no workaround is attempted.
  6. Report — a fixed-shape summary: bug, repro, fix, docs, review, commit.

Steps run sequentially. If reproduction fails after honest effort, the skill stops and reports it — it never proceeds to fix a bug it couldn't reproduce.

Example 1 — Free-text bug (illustrative example)

Input:

/bugfix the invoice total rounds down on .5 cents instead of up

Output / Result:

## 🐛 Bugfix: invoice total rounds .5 cents down instead of up

**Bug**      ROUND_HALF_DOWN applied in `billing/invoice.py:calculate_total`
**Repro**    tests/billing/test_invoice.py::test_half_cent_rounding — failed, now passes
**Fix**      switched Decimal rounding mode to ROUND_HALF_UP (`billing/invoice.py`)
**Docs**     none affected
**Review**   2 issues fixed (0/1/1), 0 remaining
**Commit**   a3f91bc — 2 files

Example 2 — Bug-report file (illustrative example)

Input:

/bugfix Documentation/Backlog/bug-bulk-users-200-on-partial.md

Output / Result:

## 🐛 Bugfix: POST /users/bulk returns 200 on partial failure

**Bug**      HTTP 200 returned even when some rows fail validation (`routes/users.py:bulk_create`)
**Repro**    tests/routes/test_users_bulk.py::test_partial_failure_returns_207 — failed, now passes
**Fix**      status code now 207 Multi-Status when at least one row fails (`routes/users.py`)
**Docs**     Updated API reference: docs/api/users.md — status codes table
**Review**   1 issue fixed (0/0/1), 0 remaining
**Commit**   d7c04e1 — 3 files

Related tools