/bug-fix

Fix a bug properly — root cause, minimal fix, regression test, verified

What it does

/bug-fix <description> starts a goal whose condition is a full debugging workflow, then keeps the agent working until every step is done. It's the difference between "the symptom went away" and "the bug is fixed and can't come back".

/bug-fix login returns 500 when the email contains a plus sign

The workflow it enforces

The condition it sets requires all four steps, in order:

  1. Reproduce it, or pin down the exact root cause in the code — not just the symptom
  2. Apply the smallest correct fix — no refactoring, no touching unrelated code
  3. Add or update a regression test that fails before the fix and passes after
  4. Run the relevant tests (plus typecheck/lint if applicable) and show the output

It is only considered done when the fix is in place, a regression test exists and passes, and no existing tests broke.

Note

Step 3 is the one that matters most and the one an agent skips if you don't ask for it. A fix without a failing-then-passing test is unproven — it may not even be addressing the bug you saw.

Why not just ask?

Asking "fix the login bug" ends the turn as soon as the model has something plausible to say. /bug-fix sets an explicit finish line, so the session continues until the work is actually complete — including running the tests and showing you the output.

Managing it

/bug-fix is /goal with a pre-written condition, so you manage it with the goal sub-commands:

Command Effect
/goal status how far it's got, budget used, last verdict
/goal pause stop auto-continuing
/goal resume resume with a fresh budget
/goal clear abandon it

The same safety limits apply — 25 turns, 15 minutes, 200,000 tokens per burst, whichever comes first. Hitting one produces a wrap-up report rather than silently stopping, and /goal resume starts a new burst.

Writing a good description

The description becomes part of the condition, so specifics carry all the way through.

Instead of Write
fix the login bug login returns 500 when the email contains a plus sign
tests are broken auth.test.ts "rejects expired token" fails since the JWT bump
it's slow GET /search takes >2s when the query has more than 3 terms

Include the error message, the failing test name, or the exact input if you have them. Anything that makes the bug reproducible makes step 1 possible.

Where it improves the result

Use case Effect Why
Bug-Fixer Much better What it exists for. The regression-test requirement is the difference between "the symptom stopped" and "this can't come back".
Testcase creation Better A side effect worth having: every fix leaves behind a test that provably fails without it. Over time that's the coverage you actually wanted.
Migration Better Use it for each breakage a migration causes, not for the migration itself — /goal drives the bulk work, /bug-fix handles the fallout properly.
Feature Development Some Only for defects found mid-build. For the feature itself, the condition doesn't fit.
Reviewer Little A review finds unknown defects across a codebase; /bug-fix fixes one you can already name. Use /review.

The signal is whether you can point at one defect. "The login test fails after the JWT bump" fits. "Find everything wrong with this service" is a review.

Related