commit

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