By name: kc-pr-reorg description: Use when a feature branch has messy interleaved commits that need reorganization into logical groups before PR review. Triggers include "squash commits", "clean up history", "reorganize commits", "reorder commits", "too many commits". Not for simple squash-all — use git merge --squash instead.
Commit Reorganization
Non-interactive technique for reorganizing N commits into M logical groups without git rebase -i.
When to Use
- Feature branch with 5+ commits needing logical grouping
- Commits interleaved by concern (feat mixed with test mixed with fix)
- Agent environment where interactive rebase is unavailable
- PR reviewer needs clean, reviewable history
Technique
1. Backup (BLOCKING — never skip)
git branch backup/<branch>-pre-reorg
2. Analyze
git log --oneline main..HEAD
List all commits. Categorize each by concern (feat, test, refactor, docs, chore). Note original chronological order — you will need it in step 4.
3. Plan Groups
Present a numbered grouping plan to the user. Recommended ordering:
- docs/design (context first)
- refactor (prep work)
- feat (core implementation)
- test (validates feat)
- chore (tooling, config)
Each group becomes one commit. Commit message descriptions follow the unified language preference — see plugin CLAUDE.md.
Get user approval before proceeding.
4. Reset and Rebuild
# Detach from current history
git reset --soft main # All changes staged
git reset HEAD -- . # Unstage all
git reset --hard main # Clean working tree
git clean -fd # Remove untracked files (reset --hard misses these!)
Then for each group, cherry-pick its commits in original chronological order within the group:
git cherry-pick --no-commit <commit1> <commit2> ...
git commit -s -m "feat(scope): description" # description follows unified language preference; prefix stays English
Repeat per group.
5. Verify (BLOCKING — never skip)
git diff backup/<branch>-pre-reorg
Must be empty. If not, something was lost — investigate before force pushing.
6. Force Push
git push --force-with-lease
Common Mistakes
| Mistake | Fix |
|---|---|
Skip git clean -fd after reset |
New files from old commits remain, break builds |
| Cherry-pick conflicts cascade | Stop. git reset --hard main, re-plan group boundaries |
| Group by type ignoring time order | Within each group, preserve original commit order |
| Skip backup branch | Unrecoverable if something goes wrong |
Skip git diff verification |
Silent data loss — always verify zero diff |
Use git add -p for splitting |
Too slow, error-prone. Cherry-pick whole commits into groups |
Recovery
If rebuild goes wrong at any point:
git reset --hard backup/<branch>-pre-reorg
Start over from step 2 with revised grouping plan.
Decision: Reorg vs Simpler Alternatives
digraph {
"How many commits?" [shape=diamond];
"Need to preserve individual commits?" [shape=diamond];
"git merge --squash" [shape=box];
"This skill (kc-pr-reorg)" [shape=box];
"Keep as-is" [shape=box];
"How many commits?" -> "git merge --squash" [label="< 5"];
"How many commits?" -> "Need to preserve individual commits?" [label=">= 5"];
"Need to preserve individual commits?" -> "Keep as-is" [label="no, squash all"];
"Need to preserve individual commits?" -> "This skill (kc-pr-reorg)" [label="yes, logical groups"];
}