Bug Fix

/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 | No | first open bug | Specific bug to work; otherwise picks the highest-severity open bug | | --scanner | 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 code
• classification === "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  --newStatus in-fix --note "Starting fix; pre-review: "

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:

1. Reproduce the bug's failure mode in a new test case based on bug.evidence.testName and bug.evidence.assertionMessage
2. Run only that test — it must fail with the same symptom as the registered bug
3. 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 

| 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-" 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(): message that references the bugId
• Any regression bugs from Step 7 are either fixed or filed

Output template

Bug-Fix Summary — 
  Classification: 
  Scanner: 
  Severity: 

  Pre-fix review:    
  TDD test added:    
  Fix commit:        ): >
  Validate-fix:      
  Post-fix sweep:    >

  Status: 

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

• [.github/skills/code-review/SKILL.md](../code-review/SKILL.md) — Step 2 pre-fix review
• [presets/shared/skills/forge-quench/SKILL.md](../../../presets/shared/skills/forge-quench/SKILL.md) — complexity-class refactor pass before patching
• [.github/instructions/self-repair-reporting.instructions.md](../../instructions/self-repair-reporting.instructions.md) — meta-bug routing
• [pforge-mcp/crucible/modes/bug-batch.mjs](../../../pforge-mcp/crucible/modes/bug-batch.mjs) — multi-slice fix-plan lane

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: srnichols
• Source: srnichols/plan-forge
• License: MIT

Install and usage instructions live in the source repository linked above.