fix-bug

name

fix-bug

description

Drives a bug fix end to end with the reproduce → failing test → fix discipline. Use when the user reports broken behavior: "fix this bug", "X is broken", "X stopped working", "users are seeing Y", pastes an error/stack trace, or points at a defect issue ("fix issue #N"). Bug-shaped work differs from feature-shaped work: you must see it fail before you change anything, and the proof of the fix is a test that goes red → green. For new functionality use /webdev:new-feature; for a red CI check use /webdev:fix-ci.

Fix Bug (orchestrator)

The bug-shaped counterpart to /webdev:new-feature. Sequencing matters more here: the discipline is reproduce → root-cause → failing test → fix → sibling sweep, in that order. Resolve all project commands via /webdev:detect-stack.

Hard rule: never fix what you haven't seen fail

A fix applied to an unreproduced bug is a guess wearing a commit message. If you cannot make the bug happen, you cannot know the fix works — and "it looks right" is how the same ticket comes back in two weeks. Reproduce first; if you genuinely can't, say so and gather more information rather than shipping a speculative patch.

0. Classify, then branch

If the report is unambiguously a bug, branch now. If it's only an issue reference (fix issue #N) or otherwise ambiguous between a defect and a change request, do Step 1's classification first — read the issue (gh issue view <n>) — and branch only once it's confirmed bug-shaped. A ticket that turns out to be missing functionality is /webdev:new-feature work; branching fix/ before reading it strands you on a fix-prefixed branch that /webdev:open-pr maps to a fix: title for what is actually a feature (re-create the branch if you already made it).

Invoke /webdev:new-branch with the project's bug-fix prefix — fix/ by default, but honor a branchPrefixes override in .claude/webdev.json (a project using bugfix/ or bug/ means that one). Issue number in the name when there is one, e.g. fix/412-avatar-upload-500.

1. Pin down the report

Establish, from the user / issue (gh issue view <n> when a number exists) / error text:

• Expected vs actual behavior — one sentence each
• Repro steps as reported, and the environment they happened in (which user/role, which page/endpoint, which data)
• The exact error (message + stack trace) if there is one

If any of these are missing and not inferable, ask now — one question up front beats a wrong fix later.

2. Reproduce it

Make the bug happen yourself before reading much code — the failure output usually localizes the problem faster than code-reading does. Cheapest applicable route:

• an existing test you can run with the bug's inputs (resolved test command)
• a direct exercise of the path — curl the endpoint, run the CLI, invoke the function in a scratch script (use a scratch dir, don't commit it)
• the running app via the resolved dev command, following the reported steps

Can't reproduce? That's a finding, not a license to guess. Check environment differences (role/permissions, data state, feature flags, locale/timezone, browser vs server), try the non-default context, and report back what you tried and what extra detail would pin it down. Only proceed on an unreproduced bug if the user explicitly accepts a speculative fix — label the PR as such.

3. Find the root cause, not the symptom site

The line that throws is rarely the line that's wrong. Trace backwards from the failure: what produced the bad value / wrong state / missed call? Keep asking "and what caused that?" until you reach a decision the code makes incorrectly — that's where the fix belongs. Patching at the symptom site (a null-check here, a try/catch there) leaves the real defect in place and converts a loud bug into a quiet one.

State the root cause in one sentence before writing the fix. If you can't, you don't understand the bug yet.

Check /webdev:plan-inventory's triggers before fixing: if the root cause lives in a value-shape invariant, shared infrastructure, or code spanning execution contexts, run the inventory first — bug fixes in shared code have the same blast radius as features there.

4. Write the failing test FIRST

Before the fix, add the test that asserts the correct behavior — and run it:

• It must fail now, for the same reason as the bug — read the failure output and confirm it matches the reproduction from Step 2. A test that fails differently is testing something else; a test that passes is vacuous.
• Name it so it documents the defect (reference the issue number where one exists).
• Put it where the project's existing tests for that unit/route live.

Red first is the point — a test written after the fix proves only that the test agrees with the code, not that it would have caught the bug. If the bug genuinely can't be reached by the project's test harness (visual layout, third-party interaction), record the manual repro steps explicitly in the PR test plan instead — and say that's what happened.

Speculative path (Step 2's unreproduced-but-user-approved case): there's no observed failure to match, so you can't honestly write a test that fails "for the same reason as the bug" — don't manufacture one. Write the test that asserts what your hypothesis says is correct, note that it couldn't be confirmed red against the real defect (never reproduced), and carry that limitation into the fix, the PR summary, and the Output — the hypothesis + verification-limits shape the Output contract defines. A speculative fix ships as a labeled hypothesis, not as proven.

5. Fix at the root cause

Minimal diff that makes the decision correct. Resist refactoring around the bug — note tempting cleanups as follow-ups instead of expanding the diff. Then prove it on whichever path Step 4 took: test path — the new test goes green; manual path (harness can't reach the bug) — re-drive the recorded manual repro and observe it no longer reproducing. Either way the Step 2 reproduction must be gone; neither path invents a test after the fact to look covered.

6. Sweep for siblings

Bugs come in families. Before declaring done, grep for the same mistake elsewhere — the same misused helper, the same copy-pasted block, the same wrong assumption in a sibling implementation. Fix siblings in the same commit with the same test treatment, or list them explicitly as follow-ups if they're genuinely separate. "Fixed the one reported instance" is the half-done state a reviewer catches.

7. Verify

Invoke /webdev:run-tests: the new test(s) plus the blast radius of the changed code (full suite only if the fix touched foundational code — that skill's canonical list). Then re-run the original reproduction end to end — for a user-facing bug, do this via /webdev:verify so the re-drive produces observed evidence (its row/verdict contract), not a remembered impression.

8. Commit and PR

Invoke /webdev:commit (type fix:, Closes #N when an issue exists). In the PR body's Summary, include the one-sentence root cause and the proof — the red → green test, or, on the manual path where the harness can't reach the bug (visual/third-party per Step 4), the manual repro that was re-driven and observed fixed, labeled as manual. For a speculative fix (Step 2, never reproduced), say so: give the hypothesis you patched and its verification limits, not a claimed red → green against a bug you never saw fail. Never describe automated coverage that doesn't exist — that's what keeps a bug-fix PR reviewable in one honest pass.

Dependency graph

/webdev:fix-bug
  ├── /webdev:new-branch        (project's bug-fix prefix — fix/ default, per branchPrefixes)
  ├── /webdev:plan-inventory    (only if the root cause trips its triggers)
  ├── /webdev:run-tests         (new test red → green, then blast radius)
  ├── /webdev:verify            (user-facing bugs — re-drive the repro, observed)
  └── /webdev:commit
        └── /webdev:open-pr

Key reminders

• Reproduce before reading, root-cause before fixing, red test before the fix.
• The symptom site and the fix site are usually different lines.
• If the "bug" turns out to be missing functionality or a behavior-change request, stop and say so — that's /webdev:new-feature work, and the reporter should confirm the new intent.

Output

Two valid terminal shapes — a no-patch investigation is a legitimate end state, not a failure to force a PR out of:

Fixed (reproduced, or speculative with explicit user approval):

• Bug: expected vs actual (one line) · Reproduced: how (or "not reproduced — speculative fix, user-approved, labeled in the PR")
• Root cause: one sentence, with file:line — or, for a speculative fix, the hypothesis you patched, marked unconfirmed
• Proof: test name + location, confirmed red → green — or, where the harness can't reach the bug (visual/third-party per Step 4), "manual verification: " stated as such — or, for a speculative fix never seen failing, the verification you could do (e.g. the new test passes) plus what stays unconfirmed against the real bug
• Siblings: fixed in-commit / follow-ups filed / none found (state which)
• Test result: scope + pass/fail · Branch · Commit SHA · PR URL

Investigated, no patch (could not reproduce; user did not approve a speculative fix):

• Bug: expected vs actual (one line)
• Attempted: repro routes tried, contexts checked (role, data state, flags, env)
• Hypotheses: ranked, with what evidence would confirm each
• Needed to proceed: the specific detail(s) that would pin it down
• No commit / no PR — nothing shipped, by design.