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:

  1. One logical change. Never mix refactoring with behavior changes. Mechanical changes (formatting, renames) get their own commits.
  2. Builds and passes tests at that point in history. No "fixed in the next commit" debt — that is what makes git bisect meaningful.
  3. The message explains WHY. The diff already shows what. Record constraints, rejected alternatives, hidden invariants.
  4. 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.
  5. Keep them small. Readable in one sitting. If it feels too big, it can almost always be split further.

Procedure

1. Assess the current state

Installs
40
First Seen
Aug 30, 2026