atomic-commits

Atomic Commits

Overview

Take a dirty working tree of uncertain provenance and produce a clean, linear sequence of atomic commits where every commit builds, every commit could be reverted in isolation, and git bisect will land on a meaningful unit when chasing a regression. The agent does not assume it remembers what changed — it investigates, classifies, groups, then commits.

Core Principle: The Bisect Test

Every commit must satisfy this test:

If git bisect lands on this commit alone, can the project still build, run its test suite, and be deployed? And does the commit's title accurately describe a single coherent change?

This produces two rules that govern every grouping decision:

1. Smallest buildable + deployable unit. Do not split a change so finely that an intermediate commit fails to compile, breaks tests, or leaves an import dangling. A new module and its first caller belong together if the caller would not compile without the module.
2. No smaller, no larger. Do not bundle two unrelated improvements just because they touched the same file. Two bug fixes in auth.py should be two commits — bisect cannot tell which one introduced a regression if they ship together.

When the two pull in different directions, prefer the smaller commit and add the minimum scaffolding (e.g., a stub, a no-op default) needed to keep the tree green.

Workflow

Phase 1 — Survey

Before classifying anything, get a complete picture of the working tree.

git status --short
git diff --stat
git diff                       # unstaged
git diff --cached              # staged (rare in this workflow but check)
git log -10 --oneline          # recent history for tone/style of messages

If there are staged changes already, decide whether to keep them as-is (commit first) or unstage to reclassify (git reset HEAD) — but never use destructive resets. When unsure, ask the user.

Phase 2 — Investigate

Treat the diff as code written by someone else. For each modified file: