recomposing-commits

Recomposing Commits

Overview

Analyze messy commits → isolate in a worktree → let user review → apply back.

Core principle: The original branch is NEVER modified until the user explicitly approves the new history. Worktree isolation and the review gate are non-negotiable — even if the user says "just do it" or "I trust you, skip review."

Announce at start: "I'm using the recomposing-commits skill to reorganize your branch history."

---

Safety Check — Do This First

git rev-parse --abbrev-ref HEAD

Refuse immediately if the current branch is any of: main, master, dev, develop, development, staging, production, release, or matches release/* or hotfix/*.

⛔ Recomposing commits on '<branch>' is not allowed.
This skill only works on feature branches.
Please switch to your feature branch first.

Also refuse if HEAD is detached (the command above prints HEAD instead of a branch name):

⛔ You're in a detached HEAD state, not on a branch.
This skill needs a real branch to reset back onto at the end. Check out a branch first.

Also check for a dirty working tree before doing anything else:

git status --porcelain

If this prints anything, stop:

⛔ You have uncommitted changes. These won't be included in the recompose,
and they'll be at risk when the original branch is reset at the end.
Please commit or stash them first.

Do NOT create a workaround branch. Do NOT proceed on any of the above. Refuse and stop.

---

When to Use

• Commits are WIP/messy and a PR is coming
• Multiple unrelated changes were mixed into the same commits
• Commit messages are unclear ("fix", "WIP", "stuff")
• Commits need to be split, merged, or reordered

Do NOT use when:

• History is already clean
• You are on a protected/shared branch (refuse instead)
• There is only one commit to restructure
• The range contains a merge commit (see Step 3 — not supported, linear history only)

---