Skip to content
Skillsheet

minimal-fix

minimal-fix

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
Category: loop-engineering
  • minimal-diff
  • surgical-change
  • bug-fix
  • scope-discipline
  • scope-creep
  • regression-test

Install this skill

npx . --tool claude-code --only minimal-fix

Run from a git checkout of this repo — see the README for details.

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