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 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.