organize-commits
Installation
SKILL.md
Organize Commits
Restructure a branch's work into a sequence a reviewer can read one commit at a time, where every commit builds and passes tests on its own.
A well-organized commit log is one of the places understanding lives longest: each commit message carries the "why" its diff cannot express, and the sequence itself teaches the reviewer how the change was reasoned. This skill produces that artifact.
Principles
Every commit must satisfy all of these:
- One logical change. Never mix refactoring with behavior changes. Mechanical changes (formatting, renames) get their own commits.
- Builds and passes tests at that point in history. No "fixed in the next commit" debt — that is what makes
git bisectmeaningful. - The message explains WHY. The diff already shows what. Record constraints, rejected alternatives, hidden invariants.
- Order carries meaning. Typically: preparatory cleanup/refactor → infrastructure/additions → new behavior → call-site migration → dead code removal → tests/docs. A later commit must never partially revert an earlier one.
- Keep them small. Readable in one sitting. If it feels too big, it can almost always be split further.