Rework commits

Rework Commits

Optimize history for human review without changing the final code. Preserve a recovery path before rewriting anything.

Safety Rules

• Never rewrite a default, protected, or shared branch.
• Never use git reset --hard, plain git push --force, or automatic stashing.
• Never include unrelated user changes, secrets, generated artifacts, or ignored files in a commit.
• Prefer non-interactive Git commands. Set GIT_EDITOR=true only for commands that could otherwise open an editor.
• Treat an explicit request to rework commits as authorization to rewrite local feature-branch history after creating the recovery point. Always obtain confirmation immediately before force-pushing previously published history.

Workflow

1. Inspect repository state.
   • Read applicable repository instructions.
   • Identify the current branch, default branch, upstream, merge base, worktree status, in-progress Git operations, and commits unique to the branch.
   • Stop on the default branch or during a merge, rebase, cherry-pick, or bisect.
2. Require a clean, complete snapshot.
   • Inventory staged, unstaged, and untracked files.
   • If the worktree is dirty, do not stash or stage everything automatically. Ask the user to finish or scope the changes, or obtain approval for a temporary WIP snapshot containing explicitly listed in-scope files.
   • Continue only when the intended final result is represented by a clean HEAD.
3. Establish the recovery point.
   • Record the original branch name, commit hash, and tree hash.
   • Create a uniquely named local backup branch under backup/rework-commits-... pointing to the original tip and report its name.
   • Keep the backup until the rewritten branch is verified and any requested push succeeds.
4. Determine the exact rewrite scope.
   • Use the user-specified base when provided; otherwise derive the repository's default branch and merge base.
   • Inspect the complete base-to-tip diff and every branch commit before planning.
   • Exclude pre-existing upstream work and unrelated changes.
5. Plan semantic commits before resetting.
   • Give each commit one reviewable purpose and explain why it exists.
   • Order prerequisites before dependents: schema and configuration, domain or backend behavior, API or integration, UI, then documentation or cleanup when applicable.
   • Keep refactors separate from behavior changes unless separation would make either commit invalid.
   • Pair tests with the behavior they verify, except for an intentionally protected test-first contract commit.
   • Ensure each proposed commit leaves the repository coherent and is small enough to review independently.
6. Rebuild the branch.
   • Show the proposed commit sequence before rewriting.
   • Reset the feature branch to the merge base with a non-destructive mixed reset so the final tree remains in the worktree.
   • Stage explicit paths or hunks for one planned commit at a time; never use git add . as a shortcut.
   • Inspect the staged diff, confirm it contains exactly one concern, then commit with a descriptive message that explains intent.
   • Run focused verification for the commit when feasible before continuing.
7. Prove content preservation.
   • Confirm the worktree is clean.
   • Compare the rewritten HEAD with the original tip and require an empty diff; compare tree hashes when possible.
   • Review the new log and base-to-head diff to confirm every original change appears exactly once and no new content was introduced.
   • If validation fails, stop and restore or offer recovery from the backup branch rather than improvising.
8. Push only when requested.
   • For an unpublished branch, push normally and set the upstream.
   • If published history was rewritten, explain the impact and obtain confirmation immediately before using git push --force-with-lease.
   • Never force-push a shared branch or use plain --force.
9. Finish the handoff.
   • Keep the backup branch until push verification succeeds; remove it only with user approval.
   • Use the review-changes skill to run the final review and generate reviewer questions and pull-request context from the polished history.

Output

Report the merge base, recovery branch and original hash, final commit sequence, verification run per commit, proof that the final tree is unchanged, push status, and exact recovery instructions if anything failed.