Split Commits

Split Commits

Turn an overgrown working tree into a short sequence of focused local commits. Assemble each commit in the index first, hand it to $git-commit for the message, then commit within the user's authorized scope. Ask for confirmation when that batch is not already covered. Do not push as part of this skill.

Authorization

Read the current request and prior approvals together. An explicit request to split and commit the intended changes can authorize the whole sequence; approval of a particular batch covers only that batch. A request for a proposed split or messages alone does not authorize commits. Honor any instruction to confirm each batch, and do not treat silence as approval. Before asking again, check whether the existing authorization already covers the action and scope.

Workflow

1. Inspect the current Git state.
   • git status --short
   • git diff --stat
   • git diff --cached --stat
2. Decide whether the work should be split. Split when one or more of these are true:
   • the changes contain multiple independent concerns
   • refactors and behavior changes are mixed
   • tests belong to only one part of the implementation
   • generated or lock files should travel with only one subset
   • a file contains unrelated hunks that would produce a misleading single commit
3. Write a short commit plan before staging.
   • Aim for 2-5 commits.
   • Give each commit one purpose and one likely Conventional Commit type.
   • Order commits so each one is understandable on its own.
4. Respect the current index.
   • If staged changes already match the next planned commit, keep them.
   • If staged changes mix unrelated concerns, preserve their content and repartition only when existing authorization covers reshaping that index; otherwise ask before changing it.
5. Stage only the next logical batch.
   • Use git add <path> for whole files.
   • Use git add -p <path> when only some hunks belong.
   • Avoid git add . unless the remaining work is intentionally one batch.
6. Verify the staged batch.
   • git diff --cached --stat
   • git diff --cached
   • Confirm no secrets, unrelated files, or accidental churn are included.
7. Invoke $git-commit and use it to draft the commit message from the staged diff only.
8. Review the proposed message against the staged diff.
   • Keep it if accurate.
   • Tighten it if it overstates the change or merges multiple concerns in the wording.
   • If $git-commit indicates the staged set is still mixed, do not commit it. Refine the staged batch and rerun $git-commit.
9. Present the staged diff summary and finalized message. Check them against the authorized sequence or batch.
   • If covered, continue without another approval round. Otherwise ask for confirmation for this concrete batch and wait.
   • If the user declines, refine the staged batch or the message and ask again.
10. Run git commit with the finalized message only when the staged batch is covered by explicit user authorization.
11. Re-run git status --short and continue with the next planned batch until the intended local commits are created.

Grouping Heuristics

Prefer splitting by intent, not by directory alone.

Good commit boundaries:

• a bug fix with the tests that prove it
• a pure rename or move isolated from behavior changes
• a mechanical formatting or codemod sweep isolated from semantic edits
• a dependency bump paired with the code or config required for that bump
• documentation that belongs to a single feature or refactor

Poor commit boundaries:

• "backend files" vs "frontend files" when both implement one feature
• tests separated from the code they validate unless the repo already expects that pattern
• arbitrary file-count balancing
• one commit per file when the behavior change spans several files

If two changes cannot be described honestly with one subject line, they likely deserve separate commits.

Guardrails

• Do not push.
• Do not amend unless the user explicitly asks.
• Do not run git commit outside the authorized batch or sequence, or bypass a requested per-batch confirmation.
• Do not use destructive commands such as git reset --hard or git checkout --.
• Do not silently unstage or restage a mixed index; explain the intended repartition and ask first unless that action is already authorized.
• Do not ask $git-commit to summarize unstaged changes. It must see staged changes only.
• Stop and ask if the remaining edits are too entangled to split without guessing intent.

Completion

Before finishing:

• ensure every requested local commit exists
• leave any intentionally uncommitted changes in the working tree
• report the created commit subjects or SHAs to the user
• do not push or open a PR