Commit

Intent

Carve changes into surgical commits: one coherent change, minimal blast radius, and at least one feedback signal before committing.

When to use

• •“Split this into micro commits.”
• •“Stage only the minimal change and commit it.”
• •“Keep the commits tiny, keep checks passing.”

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.

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) Commit

• •Use a terse message; optimize for clarity, not poetry.
• •Commit only after at least one signal passes.

6) Repeat

Repeat until the working tree is clean or the 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.

Resources

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