---
name: minimal-fix
description: Fixes one specific problem with the smallest diff that could work — no drive-by refactors, no speculative abstraction. Use inside autonomous loops, when addressing a single CI failure or review comment, or whenever a small targeted change is safer than a broad one.
category: loop-engineering
keywords: minimal-diff, surgical-change, bug-fix, scope-discipline, scope-creep, regression-test
---

# Minimal Fix

## When to apply

Use when there is **one specific problem**: an exact failure message, a reviewer comment, or an issue description. This is the maker half of the maker/checker loop — it exists to keep autonomous fixes small enough to verify.

## Inputs

- The exact failure message, comment, or issue
- The implicated file(s), if known
- The project's build/test commands (from AGENTS.md or project skills)
- The path denylist (never edit `.env`, `auth/`, `payments/`, secrets)

## Workflow

1. **Reproduce** — Confirm the failure locally if possible. A fix for an unreproduced bug is a guess.
2. **Find the root cause** — The minimal *cause*, not the nearest symptom. Changing a distant file to mask a local bug is not minimal.
3. **Change only what's required.** Explicitly banned while in minimal-fix mode:
   - Drive-by refactors and renames
   - Formatting sweeps over untouched code
   - "While I'm here" dependency bumps
   - New abstraction layers for a single caller
4. **Test the change** — Run the tests/lint relevant to the touched area, not necessarily the whole suite.
5. **Report** — What changed, why, what you ran, and what you deliberately did NOT change.

## Worked example

**Failure**: CI reports `TypeError: Cannot read properties of undefined (reading 'map')` in `UserList.tsx:42`.

```
1. Reproduce: bun run test → UserList test fails with the same TypeError
2. Root cause: users prop is undefined when the API returns an empty array
   (the component assumes users is always an array, but the API omits the
   field when empty)
3. Change: one line in UserList.tsx — default the prop:
     const items = (users ?? []).map(...)
   NOT changed: the API response shape (separate issue), the component's
   prop types (would require a larger refactor), the test file's imports.
4. Test: bun run test → UserList test passes. bunx tsc → no errors.
5. Report:
   Changed: src/components/UserList.tsx (1 line: nullish-coalesce default)
   Why: users prop was undefined when API omits the field on empty results
   Ran: bun run test, bunx tsc --noEmit
   Deliberately did NOT change: API response shape, prop types, imports
```

## Rules

- One fix per run. If a second problem appears, file it (triage) — don't absorb it.
- If the minimal fix reveals the real problem needs a design change, stop and escalate with evidence; do not half-implement a redesign.
- Smallest diff that could work — not the smallest diff that hides the symptom.

## Related skills

- [loop-verifier](/skills/loop-verifier) — Checks the fix against scope/intent/tests before approval.
- [lean-implementation](/skills/lean-implementation) — The same discipline for feature work, not just fixes.