Minimal Bug Fix

Applies the smallest possible surgical code modification that cures a verified bug. Strictly avoids incidental formatting, refactoring, or scope creep.

1. Purpose

Fix a defect with minimal diff footprint. A "Minimal Bug Fix" changes only the offending logic lines and leaves all adjacent code, style, and formatting untouched.

2. When to Use

Use this skill when:

• A bug has been reproduced via bug-reproducer.
• Patching production defects where small diffs reduce review risk.
• Fixing regression test failures.

3. When Not to Use

• Do not use to restructure or modernize code style; use small-refactor.
• Do not use before proving the bug exists; use bug-reproducer.
• Do not use to write brand new features; use task-brief.

4. Required Inputs

• reproduction_command: The command that proves the bug exists (fails before fix).
• target_file: The specific file containing the defect.
• root_cause: The reason for the bug (e.g., missing null check, off-by-one loop).

5. Missing-Input Behavior

1. If no reproduction command is available: stop and run bug-reproducer first.
2. If root_cause is uncertain: isolate cause by inspecting git blame or local logs before editing.
3. Never touch lines outside the affected function.

6. Procedure

Follow these numbered actions:

1. Action 1: Verify Pre-Fix Failure
   • Run the reproduction command. Confirm it fails.
2. Action 2: Draft Minimal Edit
   • Identify the exact 1 to 5 lines causing the failure.
   • Guard against edge cases (null, undefined, 0, negative values).
3. Action 3: Apply the Patch
   • Modify only the necessary lines.
4. Action 4: Verify Post-Fix Success
   • Run the reproduction command. Confirm it now passes.
5. Action 5: Run Entire Test Suite
   • Ensure no regressions were introduced.
6. Action 6: Emit Fix Summary
   • Format using Section 8.

7. Decision Rules

• If the diff exceeds 15 lines: stop and check whether a simpler fix exists.
• If existing tests break after the edit: revert the edit immediately and re-analyze the root cause.
• Never reformat or change quote styles in untouched lines.

8. Output Format

Emit the fix summary using this template:

### Minimal Bug Fix: [Bug Title]

- **File Modified**: `[relative file path]`
- **Lines Changed**: [Count]
- **Verification**: [PASS | FAIL]

#### Patch Summary
[1-2 sentences explaining what was changed and why.]

#### Diff
```diff
- [Old code]
+ [New code]

Verification Evidence

• Pre-fix command output: [Failing error summary]
• Post-fix command output: [Passing result]
• Test suite output: [All tests passing]

## 9. Verification Checklist
- [ ] Reproduction command failed before the fix.
- [ ] Reproduction command succeeded after the fix.
- [ ] Full test suite (`npm test`, `pytest`) passed without regressions.
- [ ] Diff is strictly minimal with zero gratuitous whitespace/style edits.

## 10. Common Failures and Recovery
| Failure Symptom | Cause | Recovery Action |
| :--- | :--- | :--- |
| Incidental refactoring | "Fixing" other code while in file | Revert unrelated edits using git diff check. |
| Off-by-one recurrence | Incomplete edge check | Add explicit boundary test for <= vs <. |

## 11. Stop or Escalation Conditions
Stop and escalate when:
- Fixing the bug requires an architectural redesign or database schema migration.

## 12. Examples

### Example 1: Successful Execution
**Input:**
```text
Target: src/math.js
Repro: node -e "require('./src/math').divide(10, 0)"
Bug: Returns Infinity instead of throwing Error.

Output:

### Minimal Bug Fix: Prevent Zero Division in divide()

- **File Modified**: `src/math.js`
- **Lines Changed**: 3
- **Verification**: PASS

#### Patch Summary
Added an explicit check for `divisor === 0` to throw an `Error("Division by zero")`.

#### Diff
```diff
 function divide(a, b) {
+    if (b === 0) {
+        throw new Error("Division by zero");
+    }
     return a / b;
 }

Verification Evidence

• Pre-fix: Returned Infinity
• Post-fix: Throws Error: Division by zero
• Test suite: npm test -> 28 passed, 0 failed

### Example 2: Ambiguous or Missing Input
**Input:**
```text
Fix the frontend bugs.

Output:

### Minimal Bug Fix: Halted - No Target or Reproduction

- **Status**: Halted

Cannot apply a minimal fix without:
1. Target file path.
2. Concrete reproduction steps or test command.
Please run `bug-reproducer` or specify the failing file.

Example 3: Expected Final Output

Output:

### Minimal Bug Fix: Guard Null Token in Auth Header

- **File Modified**: `src/auth.ts`
- **Lines Changed**: 1
- **Verification**: PASS

#### Patch Summary
Used optional chaining on `authHeader` before calling `.split(' ')` to prevent null pointer exceptions on unauthenticated requests.

#### Diff
```diff
- const token = authHeader.split(' ')[1];
+ const token = authHeader?.split(' ')[1] ?? null;

Verification Evidence

• Pre-fix: TypeError: Cannot read properties of undefined (reading 'split')
• Post-fix: Returns null token and 401 response
• Test suite: npm test tests/auth.test.ts passed