bug-fix

# Bug Fix

## Required Skills

Load these skills based on bug scope (see Steps 2 and 5 for when):

1. `framework:knowledge-priming` -- Load project context (tech stack, architecture, conventions) so fix match real project (always)
2. `framework:context-anchoring` -- Load existing feature context doc when available, capture root cause + repair decisions for future (always)
3. `framework:learning-harvest` -- Load prior operational learnings inform diagnosis; harvest new patterns at session end (always)
4. `framework:collaborative-judgment` -- Surface meaningful repair trade-offs instead of silent patch choice (always)
5. `framework:clean-code` -- Keep fix focused, readable, minimal scope (always)
6. `framework:test-quality` -- Create + validate failing regression test that proves bug exists + fix works (always)
7. `framework:architecture` -- Validate layer placement, dependency direction, correct repair location (conditional)
8. `framework:domain-driven-design` -- Validate invariants, aggregate boundaries, domain behavior when bug involves domain logic (conditional)
9. `framework:secure-coding` -- Validate trust boundaries, input handling, authorization, injection safety when bug touches security-sensitive code (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". Prior learnings about failure modes, fragile areas, and recurring defect classes inform diagnosis from the start.
- 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."

If can't state bug clearly yet, keep gathering 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. Don't guess and patch speculatively.

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]

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**:

- If can't create stable failing automated test, pause, 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 out