Small, Focused Changes
Prefer a series of small, single-concern changes over one large one. Small diffs are statistically more correct, faster to review, and easy to revert if something goes wrong. This applies to PRs and to delegated work — chop dispatches into small units too.
The rule
One concern per change. Each unit should be independently shippable and independently revertible. If reverting your change would also undo an unrelated improvement, it's two changes wearing one hat.
Why
- Correctness: smaller diffs have fewer places for bugs to hide and get genuinely reviewed (large PRs get rubber-stamped).
- Reversibility: a one-concern change reverts cleanly; a mega-change forces you to choose between keeping a bug and losing good work.
- Throughput: small changes merge sooner and unblock dependents instead of sitting in review.
- Bisectability: when something breaks, a history of small commits points at the cause; a few giant commits don't.
How to decompose
- Find the seams: separate refactor-then-change (first a behavior-preserving refactor, then the behavior change), interface-then-impl, scaffolding-then-feature.
- Make each unit stand alone: it should build, keep tests green, and be mergeable on its own — not "part 3 of 5 that only works with the others."
- Sequence by dependency, ship in order; later units build on merged earlier ones.
- Keep mechanical churn separate from logic: a rename or formatting sweep is its own change so the logic diff stays readable.
- For delegated work: hand out one small, reversible unit per dispatch — not a big multi-part dispatch. The same correctness/reversibility math applies one level down.
When to use / not
- Use whenever a change is more than one concern, or big enough that review would skim it.
- Not an excuse to split one atomic concern into nonsense fragments (a change and the deletion it requires ship together — see adopt-and-delete), or to ship a half-feature that breaks the build. Smallest coherent unit, not smallest possible.
Anti-patterns
- The mega-PR that mixes a refactor, a feature, and a formatting sweep — unreviewable, unrevertible.
- "I'll split it later" — the split never happens once it's written as one blob.
- A stack of units where unit N silently depends on unit N+1 (none stands alone).
- A dispatch that asks for five loosely-related things at once.
- Splitting so aggressively that no single unit builds or makes sense on its own.
1---2name: small-focused-changes3description: Small, Focused Changes4---56# Small, Focused Changes78Prefer a **series of small, single-concern changes** over one large one. Small diffs are statistically more correct, faster to review, and easy to revert if something goes wrong. This applies to PRs **and** to delegated work — chop dispatches into small units too.910## The rule11**One concern per change.** Each unit should be independently shippable and independently revertible. If reverting your change would also undo an unrelated improvement, it's two changes wearing one hat.1213## Why14- **Correctness**: smaller diffs have fewer places for bugs to hide and get genuinely reviewed (large PRs get rubber-stamped).15- **Reversibility**: a one-concern change reverts cleanly; a mega-change forces you to choose between keeping a bug and losing good work.16- **Throughput**: small changes merge sooner and unblock dependents instead of sitting in review.17- **Bisectability**: when something breaks, a history of small commits points at the cause; a few giant commits don't.1819## How to decompose201. **Find the seams**: separate refactor-then-change (first a behavior-preserving refactor, then the behavior change), interface-then-impl, scaffolding-then-feature.212. **Make each unit stand alone**: it should build, keep tests green, and be mergeable on its own — not "part 3 of 5 that only works with the others."223. **Sequence by dependency**, ship in order; later units build on merged earlier ones.234. **Keep mechanical churn separate** from logic: a rename or formatting sweep is its own change so the logic diff stays readable.245. **For delegated work**: hand out one small, reversible unit per dispatch — not a big multi-part dispatch. The same correctness/reversibility math applies one level down.2526## When to use / not27- **Use** whenever a change is more than one concern, or big enough that review would skim it.28- **Not** an excuse to split one atomic concern into nonsense fragments (a change and the deletion it requires ship together — see adopt-and-delete), or to ship a half-feature that breaks the build. Smallest *coherent* unit, not smallest possible.2930## Anti-patterns31- The mega-PR that mixes a refactor, a feature, and a formatting sweep — unreviewable, unrevertible.32- "I'll split it later" — the split never happens once it's written as one blob.33- A stack of units where unit N silently depends on unit N+1 (none stands alone).34- A dispatch that asks for five loosely-related things at once.35- Splitting so aggressively that no single unit builds or makes sense on its own.
selamy-labs