| name | commit |
| effort | xhigh |
| disable-model-invocation | false |
| description | Splits working-tree changes into logical, self-consistent commits (ordering so nothing dangles, stepping files that straddle commits through intermediate states), writes conventional-commit messages (feat/fix/docs/refactor/chore) with motivation in the body, stages explicit paths only, uses git mv for renames, never pushes/amends/skips hooks unless explicitly asked, and ends by reporting the resulting hashes against a clean tree. Includes pre-commit checks for Fabric Git-synced repos (core.autocrlf, .gitattributes, whitespace-only portal diffs). |
| when_to_use | Use when asked to commit changes — /commit, 'commit this', 'make the commits', 'commit these split logically'. |
Commit workflow
Turn the current working-tree changes into one or more well-formed
commits. Committing only — pushing, amending, rebasing, and tagging
happen only when explicitly requested, never as follow-through.
Survey first
git status --short — full picture of modified, renamed, untracked.
Note anything already staged that you did not stage.git log --oneline -10 — calibrate message style against this
repo's actual history, not assumptions.- Read the diffs (
git diff, git diff --stat, plus untracked
files) well enough to explain why each change exists, not just
what it touches. Never commit content you haven't looked at.
An empty git status --short is the whole answer. Report that there
is nothing to commit and stop; don't work through the diffs to confirm
it. git diff --stat prints nothing on a clean tree, and reading that
silence as a failed command rather than as the answer is a real failure
mode — observed 2026-09-09, three tool calls spent re-asking the same
question.
Splitting into commits
- One logical unit per commit. A rename, a new feature, and a
docs catch-up are three commits even when they touch the same file.
Test: could each commit's subject line be written without "and"?
- Review grouping is not a commit boundary. Parts approved
together in one review are still separate commits when each stands
on its own in history — independently revertible, citable, worth
landing alone. Bundle only when the parts are mutually dependent
for meaning: a claim and the caveat qualifying it, a rename and its
call sites. Tiebreak for a docs batch — which shape would you
rather read in
git log a year from now?
- Every commit must be self-consistent. No commit may reference a
name, file, or skill that doesn't exist yet at that point in
history, and none may leave the repo in a broken intermediate state.
Order accordingly (e.g. a rename lands before anything citing the
new name).
- When one file straddles commits, reach for interactive
git add -p where your harness offers it. Some do not: an agent
shell with no interactive stdin cannot drive it, and the prompt
either hangs or reads EOF. Where it is unavailable, step the file
through intermediate states instead — edit it down to the first
commit's portion, commit, restore the next portion, commit again.
Verify the final state matches the intended end state exactly.
Stepping assumes you own the whole file. If another session has
uncommitted work in it, stepping rewrites their in-flight text —
commit only what is yours and leave the rest with a note.
- Stage explicit paths only. No
git add -A / git add . — they
silently sweep in untracked or unrelated files.
- Verify the index before each commit.
git diff --cached -- <paths> must show your change and nothing else. The diff you read in
the survey is not what git add staged: the file can change in
between, and git add <path> takes every hunk in the file, not the
hunk you meant. --stat is not enough — a foreign hunk in a file you
also edited has a stat line that looks exactly right. This is the last
point at which a swept-in change is free to fix.
- Renames go through
git mv (or are staged so git detects the
rename) so history follows the file.
Messages
- Subject:
<type>: <imperative summary> — types in this order of
likelihood: docs, feat, refactor, fix, chore, test.
Lowercase after the colon, no trailing period.
- Body: explain motivation and non-obvious decisions — why the
change exists, what prompted it, provenance ("derived from X, now
deleted"), and any ordering or scoping rationale. Never restate the
diff. Wrap near 72 columns. Trivial single-file changes may skip
the body.
- Multi-line messages: from PowerShell, a single-quoted here-string
(
@' ... '@, closing delimiter at column 0); from Bash, prefer
git commit -F - fed by a quoted heredoc over -m, which sidesteps
the quoting entirely. Crossing the two exits 0 — a PowerShell
here-string handed to -m in the Bash tool commits @ as the
subject with the delimiters in the body, and neither the hooks nor
the exit code says so. Confirm with git log -1 --format=%B --stat
before reporting the commit — one call gives both the message actually
recorded and the files actually in it.
Safety rails
- Never push, amend, force, rebase, or tag unless the user asked for
that in this conversation. Commit, report, stop.
- Never
--no-verify / skip hooks; if a hook fails, fix the cause.
- If a change looks accidental or unrelated to the stated work, leave
it uncommitted and flag it rather than sweeping it in.
- Scan for identity strings — in the diff and in the message you
are about to write. An organization's account names (
AzureAD\…,
Entra accounts), tenant names, internal hostnames, and hardcoded
C:\Users\<name> profile paths get genericized before the commit,
whatever the repo's visibility. gitleaks does not cover this: it
matches secrets, not identities, and the pre-commit hook only sees
staged content, so the message is unguarded entirely. The trap is
that a commit documenting machine- or tenant-specific behaviour is
exactly where real account names read as the subject matter — and a
message, unlike a file, cannot be fixed forward.
Assume nothing catches this for you. A hook can: an
identity-guard reading a local denylist blocks a commit whose
staged diff adds a listed term, hands back a message that carries
one, and blocks the push. But it is a local hook reading a local
list — the list is itself the leak, so it lives in no repo and
travels with no clone. Unless you installed both on this machine,
nothing above is checked for you and the scan is entirely yours. Even
where it does run it knows only what is on the list, so a name it has
never seen is yours to catch, and then to add.
When another session shares this tree
Two sessions in one working tree share every file and the index, so
neither staging nor a branch isolates you — only a commit does. Suspect
it when the survey shows a path you never touched, when something is
already staged that you did not stage, when git diff --cached holds a
hunk you cannot account for from this conversation, or when the user
says so. Rule out the two innocent explanations first: your own
stepping edits, and a hook that rewrites files, which leaves its rewrite
unstaged. Neither is contention.
- Write, stage and commit in one chained command. The gap between
reading a diff and running
git add is where their hunk gets swept
in.
fatal: Unable to create '.git/index.lock': File exists is their
git command in flight, not a stale lock. Wait and retry; never
delete it.- Record what you left. Commit only what is yours, and name the
deferred piece in the commit message so
git log carries it rather
than this conversation.
Staging one hunk out of a file they are also writing:
references/concurrent-sessions.md.
Fabric Git-synced repos
Before the first commit in a repo containing *.{ItemType} folders:
check git config core.autocrlf and whether .gitattributes pins the
item folders (per rules/fabric-git-serialization.md). Whitespace-only
diffs (EOF newline, CR-stripping) in portal-owned files are
translation artifacts — do not commit them as "cleanup"; flag them and
fix the .gitattributes instead.
Finish
git status --short must come back clean, or every remaining line
must be intentionally left and mentioned in the report.- Report each commit: hash, subject, and one line on what it contains
— plus an explicit note that nothing was pushed.
