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 allows, and confirm RED. If tests cannot be executed here, say so explicitly — the reproducer then counts as unverified, and the limitations below apply.
  • Green before any fix → the bug-condition hypothesis is wrong. STOP: Do not proceed — return to Step 2 and re-localize.

Stopping rule:

• STOP: If no stable failing automated test can be created or executed, explain why before making any code changes.
• Record the closest executable reproduction you have.
• STOP: Never present a speculative fix as complete without an automated reproducer unless the user explicitly accepts the limitation.
• The bug cannot be tested directly because of tight coupling or deep integration → introduce the minimum structural seam needed to make it testable (method extraction, parameter injection, interface boundary). This is not refactoring — it is a prerequisite for regression protection. Apply framework:clean-code inline and keep the seam minimal.

Phase B — Preservation Baseline (must stay GREEN)

• Identify existing tests covering behavior outside C.
• Important adjacent behavior has no coverage → add at most 2–3 targeted characterization tests.
• Confirm every preservation-baseline test is green before applying the fix.
• These tests must remain green through every change in Step 5 — any flip to red means the fix has side effects; stop and narrow the scope.

Step 4: Choose the Minimal Safe Fix

Separate the repair strategy from the code change itself.

Before editing, decide:

• What is the root cause?
• What is the smallest safe change that corrects it?
• Which layer is the right repair location?
• Does the issue require a local patch or a small structural correction?

Default to the smallest safe fix that restores correct behavior without architectural backsliding.

Guardrails:

• Apply framework:architecture layering rules when choosing the repair location — do not patch in an outer layer when the rule belongs inward.
• Do not widen the task into unrelated cleanup.
• Do not delete or weaken the failing test just to make the suite green.
• A real fix requires a contract or design change beyond the narrow repair → stop and discuss scope explicitly; if the user agrees the scope is a design change, route to /design-blueprint.
• Do not add guard clauses, null checks, or defensive handling for inputs outside C — the code path for correct inputs must be byte-for-byte identical before and after the fix.

Multiple valid repair strategies exist with meaningful trade-offs → present them using framework:collaborative-judgment before proceeding.

Step 5: Implement the Fix

Always apply:

• framework:clean-code -- keep the delta focused, readable, and easy to reason about.
• framework:test-quality -- maintain the regression test and any nearby supporting tests.

Conditionally apply, based on the localized root cause:

• Fix changes layer responsibilities, dependency direction, or architectural flow → apply framework:architecture.
• Fix changes domain behavior, invariants, aggregate boundaries, or value objects → apply framework:domain-driven-design.
• Fix touches input validation, authorization, queries, external boundaries, or sensitive data → apply framework:secure-coding.

After implementing the fix, before presenting:

1. Re-run the regression test and confirm it is now green. Tests cannot execute in this environment → state that explicitly; never imply the test passed unrun.
2. Run the applicable atoms' Self-Validation Checklist sections against the changed code.
3. Run the applicable atoms' Active Anti-Pattern Scan checklists.
4. Fix violations before presenting the result.

Step 6: Verify Non-Regression

Verify the repair on three levels:

1. Fix proof -- the regression test that was red before the fix is now green, asserting the correct outcome rather than just the absence of the original failure.
2. Preservation proof -- tests covering behavior adjacent to the bug still pass. Preservation-baseline tests added in Step 3 must remain green. Any flip from green to red means the fix has side effects — stop and narrow the scope before continuing.
3. Structural confidence -- the fix introduced no wrong-layer workaround, no dependency violation, no weakened security posture.

When reporting completion, be explicit about the verification scope:

• What was re-run.
• What now passes.
• What was not verified, and why.

If the fix is narrow and confidence is high, say so briefly. If verification is partial, say so clearly.

Step 7: Capture Root Cause and Close the Loop

If a context doc is active (persistence accepted in Step 2), use framework:context-anchoring Enrich to preserve the important parts of the repair. In non-persistent mode, skip to the harvest below:

• Bug summary: observed vs expected behavior.
• Root cause: what actually failed, and where.
• Repair decision: why this fix was chosen over the alternatives.
• Protection added: the regression test or executable reproducer now guarding the behavior.
• Key files changed: path + role in the doc's Key Files table (skip a path already listed).

No context doc exists and the fix exposed a non-trivial design or domain lesson → suggest creating one so the lesson survives the session.

Harvest learnings: run 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. The user confirms what enters the document. STOP: run this before recommending /review below.

After the fix is complete, recommend /review when the change:

• touches multiple layers
• changes security-sensitive code
• changes domain behavior
• introduces a non-trivial structural correction