القائمة
Use when editing code, configs, or docs — make the smallest correct diff, checkpoint before risky work, and write commits that justify themselves.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Use when wiring a project's dev workflow (local stack, test tiers, gates, docs), or when naming make targets in a repo that has siblings — build a thin self-documenting Makefile facade over real scripts, name targets from the shared cross-repo vocabulary, and split env files by owner so targets consume them but never write them.
Use when you need to prove a feature actually delivers its intended outcome to a user or caller, not just that its code paths run — write executable acceptance tests against real, observable outcomes, derived from the spec before or independent of the implementation.
Use when adding any new capability to a working system — ship it behind a flag or optional collaborator that defaults to prior behavior.
Use when a spec, plan, or implementation must be independently reviewed before it is trusted, committed, or advanced to the next phase — dispatch a fresh reviewer per named lens whose job is to refute the artifact, not confirm it.
Use when building automation that edits, tests, or deploys itself — an agent that regenerates its own code, a self-updating pipeline, any loop that modifies the thing running it.
Use when about to call any integration, deployment, or hard guarantee "done" — prove it live end-to-end and capture the run as evidence.
| name | surgical-changes-with-checkpoints |
| description | Use when editing code, configs, or docs — make the smallest correct diff, checkpoint before risky work, and write commits that justify themselves. |
Change exactly what the task requires and nothing more. Save a known-good version before you risk breaking things, and write each commit so a stranger can see what changed, why, and what proved it correct.
Every time you edit a file, stage a change, or write a commit message. Especially before edits that could break a working state: migrations, dependency bumps, refactors, infra changes, anything touching code you don't fully understand yet.
Red-flag thoughts that mean STOP and apply this skill:
fix:, feat:, refactor:, docs:, test:, chore: in the Conventional Commits scheme — map these to your project's commit convention if it differs). Never blend a bugfix, a refactor, and a doc tweak into one blob.Small, single-purpose diffs are reviewable, revertable, and easy to binary-search through; a mixed blob is none of these — when it breaks something, you cannot revert one concern without losing the others, and binary-searching history to find the breaking change (git bisect) lands on a commit that did four things. A checkpoint is the difference between "undo the last commit" and "reconstruct what I had an hour ago." And a commit message that records why plus what proved it turns your history into the project's memory: months later it answers "why is this like this?" without an archaeology dig, and it lets a reviewer trust the change without re-deriving it. The cost of skipping this is paid later, by someone with less context than you have right now.
On the project this was distilled from — a hexagonal, human-in-the-loop AI agent shipped to a cloud runtime — two patterns recur. A restoration commit reads: "Restored verbatim from the pre-change commit ... No content edits; no code touched" — the scope is stated so a reviewer needs zero diff-reading to trust it. A risky-change commit reads: "Validated on a fresh throwaway cloud project ... Evidence: docs/evidence/deep-review-e2e.json" — the claim "this works" is backed by a named artifact anyone can open (your runtime need not be any particular cloud; the transferable move is cite-the-evidence-artifact). And when the human said "Surgical changes, please ... commit before so we have at least this version" and later "Do not commit, so I can see any correction you make," the agent checkpointed first, then held the fix set uncommitted for review. You can apply all three without knowing anything about that project: bound the scope and say so, cite your evidence, checkpoint before risk, and stop when asked.
Machine-check the discipline you can. Rules 4 and 7 — the conventional type prefix and the provenance trailer — are exactly the habits that decay under deadline pressure, so enforce them with a commit-msg hook rather than relying on memory. This pack does: templates/git-controls/ pairs the off-the-shelf conventional-pre-commit (which checks the header type) with a tiny POSIX-sh hook that rejects any commit body lacking a Co-Authored-By: / Evidence: / Refs: trailer — so a commit that forgets its evidence fails at write time, the same way a boundary linter fails a bad import.
What a machine can check: the commit's paperwork and its blast radius. Commit-msg gates for the conventional type prefix and the provenance trailer (git-controls-starter ships both), the opt-in Evidence: trailer on live-surface paths, and branch protection that keeps checkpoints meaningful. Diff minimality itself is judgment — but reviewable judgment, because the message states the one motivation the diff has to match.
Related skills: