bug-fix

# 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