/bug-fix

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:

1. `framework:knowledge-priming` -- Load project context so the diagnosis grounds in the real codebase. (always) 2. `framework:context-anchoring` -- Find and load the feature's context doc; capture diagnosis and repair decisions in it. (always) 3. `framework:learning-harvest` -- Load prior operational learnings at session start; harvest new ones at session end. (always) 4. `framework:collaborative-judgment` -- Surface hypotheses and repair trade-offs as structured options instead of silently assuming. (always) 5. `framework:clean-code` -- Keep the fix focused, readable, and free of drive-by changes. (always) 6. `framework:test-quality` -- Regression tests, characterization baseline, assertion quality. (always) 7. `framework:architecture` -- Layer placement and dependency direction. (conditional: layer placement is in question — Steps 2/4/5) 8. `framework:domain-driven-design` -- Domain invariants and aggregate behavior. (conditional: domain invariants involved — Steps 2/5) 9. `framework:secure-coding` -- Trust bounds and sensitive data handling. (conditional: trust boundary crossed — Steps 2/5)

Workflow

Step 1: Establish Bug Context

Start from the failure, not from a proposed fix.

• Gather the **observed behavior**, the **expected behavior**, the **reproduction path**, and any evidence: failing test, error message, stack trace, log excerpt, request payload, recent change.
• Run `framework:learning-harvest` Load behavior. Focus hint: "bug investigation — focus: reliability, quality signals".
• Run `framework:context-anchoring` Document Discovery to check for an existing context doc covering the affected feature/module:
• **Found** → Load behavior. Honor every logged decision and constraint as an active commitment while diagnosing. An open investigation of this same bug is already logged in it → confirm with the user whether to resume that investigation or start fresh.
• **Not found** → Proceed from the bug report and the current code. Do not block diagnosis on a missing context doc.

End the step by summarizing the bug in one sentence:

> "Observed X, expected Y, reproducible via Z."

**STOP:** If you cannot yet state the bug that clearly, gather more evidence before proposing any code changes.

Step 2: Reproduce and Localize

**Primary discipline**: never present a fix for a bug you have not reproduced.

Reproduce the failure using the strongest evidence available, in this order:

1. **Existing failing automated test** -- best case; use it as the regression guard. 2. **New failing automated test** -- preferred when no test exists yet. 3. **Executable reproduction path** -- command, request sequence, or deterministic manual flow when automation is not yet possible.

Localize the issue before editing:

• **Which layer is the likely source?** Use the layer definitions from `framework:architecture` to identify which architectural layer the defect originates in.
• **Production bug or test bug?** Sometimes the code is correct and the test or fixture is wrong.
• **Failure symptom or root cause?** The crashing line is often downstream of the real defect.
• **Does the bug cross a trust boundary?** If yes, `framework:secure-coding` applies to the fix (Step 5).
• **Does it involve domain invariants or aggregate behavior?** If yes, `framework:domain-driven-design` applies to the fix (Step 5).
• **Will the likely fix touch multiple layers or dependency flow?** If yes, `framework:architecture` applies to the fix (Steps 4–5).

If multiple plausible root causes remain, use `framework:collaborative-judgment` to present the leading hypotheses and what evidence would distinguish them.

Before writing any regression test, state the root-cause hypothesis explicitly via `framework:collaborative-judgment`:

> "The bug is caused by [X]. When [C holds], the correct outcome should be [P]. > We confirm this by writing a test that is red before the fix and green after."

If the user identifies a flaw in the hypothesis, revise it before writing tests.

End the step with an explicit bug contract:

> **C (bug condition):** [exact input/state triggering the bug] > **P (fix postcondition):** [what correct behavior looks like when C holds] > **Preserved:** [what must remain identical for all inputs outside C]

**STOP:** If you cannot state all three, keep localizing before writing tests.

**Persistence check** — now that the bug is reproduced and localized, decide whether to persist the investigation:

• Investigation is complex, involves multiple hypotheses, or is likely to span multiple sessions → ask whether the user wants to persist the diagnosis and repair decisions.
• A relevant context doc exists → enrich it in Step 7.
• None exists and the user wants persistence → propose creating one; confirm the doc name per `framework:context-anchoring`, then use it as the source of truth.
• The user declines persistence, or the bug is narrow and local → continue in non-persistent mode. The repair workflow still applies; decisions remain in-session.

Step 3: Add Regression Protection First

**Phase A — Bug-Condition Tests (must start RED)**

• Write the smallest failing test that fires when C holds.
• Prefer the lowest-level test that reproduces the real failure without losing signal.
• Name the test for the broken behavior, not the implementation detail.
• Assert the correct expected outcome (postcondition P), not just the absence of failure.
• Apply `framework:test-quality` inline while writing it.
• Run it against the unfixed code where the environment allo