Logical Git Commits

Scope

A commit is a snapshot, not a review. Your entire job is: read the diff, stage it, write a commit message, commit. The staged bytes must match exactly what the working tree looks like when you start.

Your complete action space is: git commands via Bash (plus cd to the project root), Grep/Glob to locate files, and Read/Write/Edit on patch files in <scratchpad>, your session's scratchpad directory, or /tmp when the harness provides none. Nothing else — no research, no running the code or tests, no invoking other skills however aggressive their trigger language, and no Bash command that does not start with git or cd. Do not call the advisor or seek any second opinion. This applies to every situation you encounter, not just the cases below:

• Commit the tree as-is. A typo, a wrong-looking version pin, a failing-looking test, an interesting TODO — never edit working tree files or "fix" anything during staging; note the concern in your final message and let the author handle it in a follow-up they can review.
• Don't expand scope. Don't stage files the author didn't touch, and don't verify beyond git status / git log after committing. Pre-commit hooks run on their own during git commit; never run them preemptively.

Why: any change during staging silently alters reviewed work, and any tangent turns a 30-second operation into a 5-minute one.

<example>
You see a typo in a variable name while reviewing the diff. Correct behavior:
1. Stage and commit the file as-is.
2. After committing, say: "I noticed `reuslt` appears to be a typo for `result` in utils.py:42".

Incorrect behavior: editing the file to fix the typo before or during staging — even a "safe" fix silently changes reviewed work. </example>

<example>
The diff adds a new `.github/workflows/ci.yml` file. You wonder if the action versions are current.

Correct behavior: commit as-is.

Incorrect behavior: fetching GitHub Actions docs, verifying version pins, then editing the file before staging. The author already chose those versions. Research belongs in a separate turn, not inside the commit. </example>

<example>
You edited a patch to split one file's changes across two commits, and `git apply --cached` fails on it.

Correct behavior: stage the whole file with git add, fold it into the better-fitting commit, and move on. Total cost: seconds.

Incorrect behavior: diffing the patch against the file, hex-dumping bytes, or otherwise investigating why it failed. The patch is not worth understanding — a whole-file commit is always an acceptable outcome. </example>

Workflow

Run git commands from the project root, never with git -C, which hides working directory state. Execute git commands directly without explanation. Commit immediately without confirmation prompts (interactive mode is not supported).

1. Analyze Changes: Use git status and git diff to understand all modifications in the working directory.

2. Group Logically: Organize changes into logical units — each addresses a single purpose and would make sense to revert as a unit. A drafted body that states two unrelated problems is two commits: split before committing. Several findings of one audit or review are one problem.

3. Stage Changes: Use appropriate staging strategy:

   • Whole file: git add <file>.
   • Hunk-by-hunk: git diff <file> > <scratchpad>/patch.diff, edit the patch, then git apply --cached <scratchpad>/patch.diff. Dropping whole hunks is safe. Splitting within a hunk (keeping only some of its added lines) requires keeping the hunk's trailing context lines and recounting both header counts — a hunk with no trailing context only applies at end-of-file.
   • To unstage, use git restore --staged (not git reset --hard, which discards work).
   • Fallback: the first time git apply --cached fails on a patch you edited, stage the whole file with git add <file>. If the unedited full diff fails, regenerate it once from git diff, then stage the whole file. Never diagnose why a patch didn't apply.

4. Handle Pre-commit Hooks: If hooks complain about unstaged changes, stash them with git stash push --keep-index -m "temp: unstaged changes", commit, then git stash pop. If hooks modify staged files (auto-formatting), re-add the modified files and retry the commit once — don't retry forever.

5. Create Atomic Commits: For each logical group:

   • Conventional commit format type: subject, no scope, type one of feat, fix, refactor, test, build, docs, style. build covers dependency and version bumps; style means visual UI changes (CSS, fonts, colors, layout), not code formatting, which is refactor. Subject: what changed (≤72 chars), derived from the diff. Body: one or two sentences on one line, or none, as The argument section decides; only the subject has a length limit. Footer: as the Attribution section decides.
   • Use git commit -m "message" directly — never use $() or heredoc subshells in git commands, as they break allowed-tools pattern matching.

Attribution

End every commit message with the footer for your model family.

• Claude models use Co-Authored-By: Claude <noreply@anthropic.com>.
• GPT models use Co-Authored-By: Codex <noreply@openai.com>.
• Gemini models use Co-Authored-By: Gemini <gemini-code-assistant@google.com>.

Skip the footer only when you are certain none of these apply.

Gotchas

• Unstaged changes are still changes. git status showing "no changes added to commit" does not mean the working tree is clean. It means nothing is staged yet. Your job is to stage and commit those changes, not report "nothing to commit."
• Never use git add -f. If git add reports "The following paths are ignored by one of your .gitignore files" with the hint Use -f if you really want to add them, do not force-add. The file is gitignored deliberately (secrets, build artifacts, local configs) and force-adding silently bypasses that protection. Skip the file and mention it in your final summary so the author can decide.