playbooks

home / skills / tkersey / dotfiles / patch

patch skill

/codex/skills/patch

This skill creates focused git patches from staged changes, validates them, and exports deterministic diffs suitable for shareable review.

npx playbooks add skill tkersey/dotfiles --skill patch

Review the files below or copy the command above to add this skill to your agents.

Files (5)
SKILL.md
4.7 KB
---
name: patch
description: Create micro-patches from staged git changes (minimal incision) with at least one validation signal per patch. Use when asked to split work into small .patch files, export/share diffs, or produce patches instead of commits.
---

# 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`

Overview

This skill creates surgical git micro-patches from staged changes, producing minimal, reviewable .patch files with at least one validation signal per patch. It treats a patch as a context-sensitive diff intended to apply cleanly against an explicit base (usually HEAD). The goal is tiny, test-checked patches that minimize merge friction and maximize apply success.

How this skill works

Identify the smallest coherent change, stage it precisely, run a tight validation command, and export a binary-safe patch from the index. The skill prefers non-commit export (git apply-style) but can produce git-am/email-style patches when commit metadata is required. Before writing a patch file it runs reverse and clean-base application checks and scans for obvious secrets.

When to use it

  • You need to split a larger change into multiple small .patch files for review or transport.
  • You want to export the currently staged changes as a patch for another developer or system.
  • You need patches instead of commits because the consumer will apply via git apply or similar.
  • You want each patch to include at least one validation signal (tests, linters, or checks).
  • You want to minimize the blast radius of edits to reduce merge conflicts.

Best practices

  • Scope each patch to one file or one conceptual area; keep changes minimal and atomic.
  • Stage surgically: prefer file-level staging in non-interactive environments and verify with git diff --cached.
  • Run a focused validation command that meaningfully exercises the change before exporting.
  • Export with git diff --cached --binary --no-ext-diff --no-textconv and verify the patch is non-empty.
  • Perform git apply --check --reverse and, when possible, a clean-base apply check (detached worktree) before sharing.
  • Scan for secrets and never overwrite existing patch files unless explicitly requested.

Example use cases

  • Break a multi-feature branch into a sequence of tiny patches to send to a reviewer who applies patches manually.
  • Export a single staged bugfix as a .patch to apply onto another branch or repository that cannot fetch the branch.
  • Iteratively produce one-test-per-patch workflow: stage the change, run the test, export the validated patch.
  • Prepare emailed patches with author/commit metadata by requesting git-am/email-style format when needed.

FAQ

Should I use format-patch/commits or index-based patches?

Use index-based git apply-style patches by default for minimal transport. Use format-patch/git-am when consumer needs commit metadata.

What validation counts as a signal?

Any deterministic check that meaningfully exercises the change: a unit test, linter, build step, or quick runtime check. Prefer the smallest check that reduces downstream risk.