Patch

Intent

Carve changes into surgical git patch files: one coherent change, minimal blast radius, and at least one feedback signal before exporting.

This skill treats a patch as a transport artifact (a context-sensitive diff), not a magical commutative “merge atom”. The goal is to make patches small, reviewable, and maximally likely to apply cleanly.

Mental model (why this is harder than it looks)

• A git patch file is a procedure over a base: it is not commutative, not associative, and not idempotent in general.
• Patch-based VCSes (Darcs/Pijul) work hard to make patch application order-independent; git-style patches don’t promise that.
• Therefore: always be explicit about the intended base (usually HEAD), keep patches tiny, and validate against a clean base.

When to use

• “Split this into micro patches.”
• “Stage only the minimal change and make a patch file.”
• “Keep the patch tiny, keep checks passing.”

Output formats (choose intentionally)

• Default: git apply-style patch from the index.
  • Use when you want “here are the staged changes” and the consumer will apply with git apply.
• Optional: git am/email-style patch (requires commits).
  • Use when the consumer needs commit message/author metadata and will apply with git am.
  • This skill prefers the non-commit path unless the user explicitly asks for format-patch.

Workflow (Surgeon’s principle)

1) Scope the incision

• Identify the smallest change that can stand alone.
• Isolate unrelated edits; avoid drive-by refactors/formatting unless required for correctness.

2) Stage surgically (non-interactive-first)

Inspect:

• git status -sb
• git diff

Stage what you intend (prefer file-level staging in non-interactive harnesses):

• git add <paths...>
• git restore --staged <paths...>

Verify:

• git diff --cached matches the intended incision.

If you truly need hunk-level staging but your environment can’t do interactive staging, ask the user to stage hunks locally or provide a patch you can apply.

3) Validate the micro scope

• Optional helper: scripts/micro_scope.py (staged vs unstaged size).
• If the staged diff is multi-concern, split it before running checks.

Heuristics that reduce downstream conflicts:

• Prefer “one file or one conceptual area” per patch.
• Avoid adjacent edits that increase diff ambiguity (e.g. unrelated edits near each other).
• Avoid formatting-only noise unless required; it increases patch context fragility.

4) Close the loop (required)

• Select the tightest available signal and run it.
• If the repo’s test/check command is not discoverable, ask for the preferred command.
• Reference: references/loop-detection.md.

5) Export patch

• Choose an output path, e.g. patches/0001-<slug>.patch.

• Before exporting, sanity-check for secrets (tokens, creds, private keys). If likely, stop and ask.

• Export the staged change as a binary-safe patch (deterministic diff output):

  • git diff --cached --binary --no-ext-diff --no-textconv --no-color > <patch-path>

• Verify the patch is non-empty:

  • test -s <patch-path>

• Verify patch correctness (two levels):

  • Fast local consistency check (works even if the changes are already present in the working tree):
    • git apply --check --reverse --binary <patch-path>
  • Strong check against a clean base (recommended when sharing externally):
    • git worktree add --detach <tmp-dir> HEAD
    • in <tmp-dir>: git apply --check --binary <patch-path>
    • git worktree remove <tmp-dir>

• Keep staged changes intact unless the user asks to unstage or reset.

6) Repeat

Repeat until the working tree is clean or remaining changes are intentionally deferred.

Guardrails

• Don’t widen scope without asking.
• Prefer the smallest check that meaningfully exercises the change.
• Don’t claim completion without a passing signal and at least one patch verification step (reverse-check or clean-base check).
• Don’t export or share secrets; if in doubt, ask before writing the patch file.
• Don’t overwrite existing patch files unless the user asks.

Notes on patch identity (optional)

• Patch identity matters for deduplication (“have we already applied this logical change?”).
• In git ecosystems you can approximate this locally with git patch-id --stable (best-effort, not cryptographic).
• Patch identity is a major reason patch-based merge can outperform diff3-style merges; see references/patch-theory.md.

Resources

• scripts/micro_scope.py
• references/loop-detection.md
• references/patch-theory.md