--- 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 ` - `git restore --staged ` 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-.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 > ` - Verify the patch is non-empty: - `test -s ` - 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 ` - Strong check against a clean base (recommended when sharing externally): - `git worktree add --detach HEAD` - in ``: `git apply --check --binary ` - `git worktree remove ` - 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`

patch

Scan your own AI components