| name | bug-fix |
| description | Guided end-to-end bug-fix workflow for Plan Forge tempering bugs — load → pre-fix review → write failing test → fix → validate → post-fix sweep → close. Composes /code-review, /clean-code-review, /forge-quench, and /test-sweep around the forge_bug_* tool surface so a fix never closes without a regression check. |
| argument-hint | [--bugId <id>] [--scanner <name>] [--no-sweep] |
| tools | ["read_file","run_in_terminal","grep_search","forge_bug_list","forge_bug_update_status","forge_bug_validate_fix","forge_analyze"] |
/bug-fix Skill — Guided Bug-Fix Workflow
Trigger
"Fix this bug" / "Work the bug queue" / "Close out bug-2026-…" / /bug-fix
Purpose
The Plan Forge bug-fix path (forge_bug_register → forge_bug_update_status → forge_bug_validate_fix) is a tight state machine but it doesn't compose with the project's skill suite by default. This skill wraps the state machine with the right skills at each transition so a fix that passes the original scanner doesn't ship a regression in a neighbour.
The bug tools surface skillAdvisory hints in their responses — this skill is the canonical realisation of those hints.
Inputs
| Flag | Required | Default | Description |
|---|
--bugId <id> | No | first open bug | Specific bug to work; otherwise picks the highest-severity open bug |
--scanner <name> | No | match all | Filter by scanner (unit, integration, ui-playwright, visual-diff, flakiness, mutation, load-stress, contract, performance-budget) |
--no-sweep | No | off | Skip the post-fix /test-sweep — only use for hot-fix paths under time pressure |
Steps
1. Load the bug
forge_bug_list --status open --severity high
Pick the bug (--bugId overrides). Read the full record: scanner, classification, affectedFiles, evidence, reproSteps. Stop and report if:
- The bug is already in a terminal status (
fixed / wont-fix / duplicate)
classification === "infra" — surface to the human; the fix is likely CI/runner config, not product codeclassification === "flake" — run /forge-troubleshoot first; a flake fix is a different workflow
2. Pre-fix review (collateral surface)
Run /code-review scoped to bug.affectedFiles. The goal is to surface related issues that should be fixed in the same commit — fixing one bug while leaving its neighbours broken trains the next agent session to keep doing the same.
For complexity-class bugs (scanner === "mutation", or /code-review flags high cyclomatic complexity in the affected functions), pivot to /forge-quench first. Quench's Chesterton's-Fence pass clarifies the logic so the fix lands on a stable shape, not on top of confusion.
3. Transition to in-fix
forge_bug_update_status --bugId <id> --newStatus in-fix --note "Starting fix; pre-review: <link/summary>"
The response surfaces a skillAdvisory field tuned to the bug's scanner — follow it for scanner-specific guidance (UI / perf / contract / mutation).
4. Write the failing test first (TDD)
Before touching production code:
- Reproduce the bug's failure mode in a new test case based on
bug.evidence.testName and bug.evidence.assertionMessage
- Run only that test — it must fail with the same symptom as the registered bug
- If it doesn't fail, the bug's reproSteps are insufficient — go back to Step 1 and gather more evidence
Why this step: forge_bug_validate_fix re-runs the original scanner. If the new failing test isn't part of that scanner's surface, the fix could pass validation without proving anything. Adding the test first guarantees the closed-loop covers the actual symptom.
5. Implement the fix
- Keep the scope tight — every file outside
bug.affectedFiles is forbidden unless absolutely necessary
- Match adjacent code style; don't restructure neighbours unless the pre-fix review flagged them
- One logical change per commit — if a fix needs more than one commit, the bug should have been a fix-plan (see
forge_crucible_submit with lane: "bug-batch")
6. Validate the fix
forge_bug_validate_fix --bugId <id>
| Verdict | Action |
|---|
fixed | The original scanner now passes. Proceed to Step 7. The response's skillAdvisory will point to /test-sweep. |
still-failing | The fix didn't take. Read attempt.details, follow the response's skillAdvisory, and revise. Do NOT increment fix attempts mechanically — every retry should be a hypothesis-driven change. |
7. Post-fix regression sweep
Unless --no-sweep was passed, run /test-sweep over the full project. The validate step only re-runs the bug's original scanner; /test-sweep catches regressions in unrelated suites.
If /test-sweep finds new failures:
- They are regressions caused by the fix. Treat them as bugs:
forge_bug_register each one with correlationId: "regression-of-<originalBugId>" and sliceRef pointing at this fix's commit.
- Decide: revert the fix and re-plan, or batch the regression fixes into a follow-up slice.
8. Close
forge_bug_validate_fix already transitions the bug to status: "fixed" on a pass. The skill is done when:
forge_bug_list --status fixed shows the bug- The fix is committed with a conventional
fix(<scope>): <description> message that references the bugId
- Any regression bugs from Step 7 are either fixed or filed
Output template
Bug-Fix Summary — <bugId>
Classification: <real-bug|flake|infra>
Scanner: <name>
Severity: <low|medium|high|critical>
Pre-fix review: <findings count + collateral fixes bundled>
TDD test added: <test name>
Fix commit: <SHA — fix(<scope>): <description>>
Validate-fix: <verdict — fixed|still-failing>
Post-fix sweep: <pass|N regressions filed as <bugIds>>
Status: <closed|still-open with reason>
When NOT to use this skill
- Infra-class bugs: route to the human; the fix is in CI / runner config, not product code
- Flake-class bugs: use
/forge-troubleshoot first to confirm flake vs. real bug
- Multi-slice fixes: submit a bug-batch lane Crucible smelt instead (
forge_crucible_submit --lane bug-batch); the resulting plan already injects /code-review and /test-sweep gates
- Meta-bugs (defects in Plan Forge itself): use
forge_meta_bug_file, not forge_bug_register
Related
