/build-fix-minimal-diff

name: build-fix-minimal-diff
description: Use when a build, test, type check, or lint is failing — locally or in CI — and the fix must be the smallest safe diff with no opportunistic refactors or unrelated changes.

Build Fix — Minimal Diff

Fix the failing build, test, or type check. Nothing else.

When to Use

• A CI build is red and blocking other work
• Tests pass locally but fail in CI — or vice versa
• Type errors or lint errors block a commit or pipeline
• A previous change broke a test that was passing

Core Rule

**Touch only what is broken. Fix the root cause. Rerun. Done.**

Any unrelated improvement — even a one-line cleanup — is out of scope for this skill.

Inputs

• The exact failing command (e.g., `npm test`, `cargo build`, `tsc --noEmit`, `pytest`)
• The full error output — exact messages and line numbers, not a summary
• Current branch state (`git status --short`, `git diff --stat`)

Workflow

1. Reproduce

Run the exact failing command and confirm it fails with the same error.

If it does not fail locally:

• Check environment differences: tool versions, env vars, installed packages, generated files
• Run a clean install (`npm ci`, `pip install -r requirements.txt`, etc.) and retry
• Document the environment discrepancy instead of guessing at a fix

2. Isolate

• Read the error output from the first line — the first error is usually the root cause; later errors are often cascades
• Identify the single failure point: file, line number, symbol, or command
• Do not start changing code until the root cause is clearly identified

3. Fix

• Apply the minimal change that addresses the identified root cause
• One change at a time
• Do not touch adjacent code, even if it looks wrong — log it as a follow-up
• Do not update test expectations to make tests pass unless the expectations were genuinely wrong (i.e., the code behavior is now correct and the test was testing the old — wrong — behavior)

4. Rerun

• Run the exact failing command: it must exit 0
• Run the full test suite to confirm no regressions introduced

5. Report

FIXED: <what was broken — command and error>
CAUSE: <root cause — specific, not vague>
CHANGE: <file:line — what was changed and why>
VERIFIED: <command run> → exit 0
REGRESSIONS: none / [list]
DEFERRED: <adjacent issues noticed but not touched>

Verification

• Exact failing command exits 0 after the fix
• Full test suite still passes
• No files modified beyond the narrowest fix

Failure Modes

• Fixing a cascade error instead of the root cause — go back to step 2
• Changing test assertions to match broken implementation — only valid when the test was wrong, never when the code is wrong
• Multiple changes at once — revert all but the smallest hypothesis and retry
• "While I'm here" scope creep — log it as a follow-up task, do not include it in this fix

Sources / Inspiration

Inspired by `Yeachan-Heo/oh-my-codex` `prompts/build-fixer.md`. Rewritten in Agent Powerups style.