---
name: bug-fix
description: "Investigate, reproduce, and safely fix a bug with regression protection. Composes context, diagnosis, architecture, code quality, and testing guardrails into a reproduce-first repair workflow. Use when the user says 'fix this bug', 'debug this', 'investigate this failure', 'patch this regression', 'repair this issue', or 'why is this broken'."
---
# Bug Fix
## Required Skills
Load these skills based on bug scope (see Steps 2 and 5 for when):
1. `framework:knowledge-priming` -- (always)
2. `framework:context-anchoring` -- (always)
3. `framework:learning-harvest` -- (always)
4. `framework:collaborative-judgment` -- (always)
5. `framework:clean-code` -- (always)
6. `framework:test-quality` -- (always)
7. `framework:architecture` -- (conditional)
8. `framework:domain-driven-design` -- (conditional)
9. `framework:secure-coding` -- (conditional)
## Workflow
### Step 1: Establish Bug Context
Start from failure, not proposed fix.
- Gather **observed behavior**, **expected behavior**, **reproduction path**, any evidence: failing test, error message, stack trace, log excerpt, request payload, recent change.
- Use `framework:learning-harvest` Load behavior. Focus hint: "bug investigation — focus: reliability, quality signals".
- Use `framework:context-anchoring` Document Discovery to check for existing context doc for affected feature/module.
- **If found** → Load it (context-anchoring Load behavior). Honor logged decisions + constraints as active commitments while diagnosing.
- **If not found** → Proceed from bug report + current code. Don't block diagnosis on missing context.
End this step, summarize bug one sentence:
> "Observed X, expected Y, reproducible via Z."
**STOP:** If can't state bug clearly yet, gather more evidence before proposing code changes.
### Step 2: Reproduce and Localize
**Primary discipline**: don't present fix for bug you haven't reproduced.
Reproduce failure using strongest evidence available, this order:
1. **Existing failing automated test** -- best case; use as regression guard
2. **New failing automated test** -- preferred when no test exists yet
3. **Executable reproduction path** -- command, request sequence, deterministic manual flow when automation not yet possible
Localize issue before editing:
- **Which layer likely source?** Use layer definitions from `framework:architecture` to identify which architectural layer defect originates in
- **Production bug or test bug?** Sometimes code correct, test/fixture wrong
- **Failure symptom or root cause?** Crashing line often downstream of real defect
- **Bug cross trust boundary?** If yes, plan load `framework:secure-coding`
- **Involve domain invariants or aggregate behavior?** If yes, plan load `framework:domain-driven-design`
- **Likely fix touch multiple layers or dependency flow?** If yes, plan load `framework:architecture`
If multiple plausible root causes remain, use `framework:collaborative-judgment` to present leading hypotheses + what evidence would distinguish.
Before writing regression test, state root cause hypothesis explicitly, use `framework:collaborative-judgment` to surface:
> "Bug caused by [X]. When [C holds], correct outcome should be [P].
> Confirm this by writing test that red before fix, green after."
If user identifies flaw in hypothesis, revise before writing tests.
End step with explicit bug contract:
> **C (bug condition):** [exact input/state triggering bug]
> **P (fix postcondition):** [what correct behavior looks like when C holds]
> **Preserved:** [what must remain identical for all inputs outside C]
**STOP:** If can't state all three, keep localizing before writing tests.
**Optional persistence check**: Now that bug reproduced + localized, decide whether persist investigation:
- If investigation complex, involves multiple hypotheses, likely span multiple sessions, ask if user wants persist diagnosis + repair decisions
- If relevant context doc exists → plan enrich in Step 7
- If none exists + user wants persistence → propose creating one, confirm doc name per `framework:context-anchoring`, use as source of truth
- If user doesn't want persistence or bug narrow + local → continue non-persistent mode. Repair workflow still applies; decisions remain in-session
### Step 3: Add Regression Protection First
**Phase A — Bug-Condition Tests (must start RED)**
- Write smallest failing test that fires when C holds
- Prefer lowest-level test reproducing real failure without losing signal
- Name test for broken behavior, not implementation detail
- Assert correct expected outcome (postcondition P), not just absence of failure
- Apply `framework:test-quality` inline
- Run against unfixed code, confirm RED
- If green before fix, bug condition hypothesis wrong — stop, re-localize
**Stopping rule**:
- **STOP:** If can't create stable failing automated test, explain why before making code changes.
- Record closest executable reproduction you have.
- Don't present speculative fix as "complete" without automated reproducer unless user explicitly accepts limitation.
- If bug can't be tested directly due to tight coupling/deep integration, introduce minimum structural seam needed to make testable (method extraction, parameter injection, interface boundary). Not refactor — prerequisite for regression protection. Apply `framework:clean-code` inline, keep seam minimal.
**Phase B — Preservation Baseline (must stay GREEN)**
- Identify existing tests covering behavior outside C
- If important adjacent behavior has no test coverage, add at most 2-3 targeted characterization tests
- Confirm all preservation baseline tests green before applying fix
- These tests must remain green through every change in Step 5 — any flip to red means fix has side effects; stop, narrow scope
### Step 4: Choose the Minimal Safe Fix
Separate **repair strategy** from code change itself.
Before editing, decide:
- What **root cause**?
- What **smallest safe change** correcting it?
- What layer **right repair location**?
- Does issue require **local patch** or **small structural correction**?
Default to smallest safe fix restoring correct behavior **without architectural backsliding**.
Guardrails:
- Apply `framework:architecture` layering rules when choosing repair location — don't patch in outer layer when rule belongs inward
- Don't widen task into unrelated cleanup
- Don't delete/weaken failing test just to make suite green
- If real fix requires contract/design change beyond narrow repair, stop, discuss scope explicitly
- Don't add guard clauses, null checks, defensive handling for inputs outside C — code path for correct inputs must be byte-for-byte identical before + after fix.
If multiple valid repair strategies with meaningful trade-offs, present using `framework:collaborative-judgment` before proceeding.
### Step 5: Implement the Fix
Always apply:
- `framework:clean-code` -- keep delta focused, readable, easy to reason about
- `framework:test-quality` -- maintain regression test + any nearby supporting tests
Conditionally apply based on localized root cause:
- **If fix changes layer responsibilities, dependency direction, architectural flow** → Apply `framework:architecture`
- **If fix changes domain behavior, invariants, aggregate boundaries, value objects** → Apply `framework:domain-driven-design`
- **If fix touches input validation, authorization, queries, external boundaries, sensitive data** → Apply `framework:secure-coding`
After implementing fix, before presenting:
1. Re-run regression test, confirm now green
2. Run applicable atom self-validation checklists against changed code
3. Run applicable anti-pattern scans
4. Fix any violations before presenting result
### Step 6: Verify Non-Regression
Verify repair three levels:
1. **Fix proof** -- regression test that was red before fix now green. Asserts correct outcome, not just absence of original failure.
2. **Preservation proof** -- tests covering behavior adjacent to bug still pass. If preservation baseline tests added in Step 3, must remain green. Any flip from green to red means fix has side effects — stop, narrow scope before continuing.
3. **Structural confidence** -- fix didn't introduce wrong-layer workaround, dependency violation, weakened security posture
When reporting completion, explicit about verification scope:
- What was re-run
- What now passes
- What not verified + why
If fix narrow + confidence high, say so briefly. If verification partial, say so clearly.
### Step 7: Capture Root Cause and Close the Loop
Use `framework:context-anchoring` Enrich behavior to preserve important parts of repair:
- Bug summary: observed vs expected behavior
- Root cause: what actually failed + where
- Repair decision: why this fix chosen over alternatives
- Protection added: regression test or executable reproducer now guarding behavior
- Key files changed: path + purpose
If no context doc exists + fix exposed non-trivial design/domain lesson, suggest creating one.
**Harvest learnings.** Use `framework:learning-harvest` Harvest behavior. Session context: "bug investigation — root cause diagnosis and repair". Synthesize and propose cross-cutting patterns from this session — root cause categories, failure modes likely to recur elsewhere, boundary condition gaps. User confirms what enters the document. **STOP: run this before recommending `/review` below.**
After fix complete, recommend `/review` when change:
- touches multiple layers
- changes security-sensitive code
- changes domain behavior
- introduces non-trivial structural correction