incremental-implementation

Incremental Implementation Skill

The big-bang failure is always the same story: three hours of changes, then "it doesn't work", then an hour of spelunking to find WHICH of forty edits broke it. Incremental work makes the last five minutes the only suspect, always. The discipline: every increment ends with the system working and verified — not "will work once the rest lands."

What This Skill Produces

• The target end state, reached via increments that were each verified green
• Stoppable points: any checkpoint is shippable, pausable, or a rollback target
• A change history where every step's intent is legible

Increment Method

1. Slice vertically to working states, not horizontally to layers. "Data layer, then logic, then UI" means nothing works until everything does. Slice so each increment is a thin working slice: one endpoint end-to-end · one case handled fully · one call-site migrated. The test for a slice: after it lands, can you demonstrate something that works?
2. Separate behaviour-preserving from behaviour-changing — always. The cardinal rule: refactor OR change behaviour in one increment, never both. Prepare-with-refactor (verify: everything still passes, nothing changed) → then the behaviour change lands small and legible. Mixing them makes every regression a two-variable mystery.
3. Verify at every increment — the same way. Green means: the relevant tests/build pass AND the previous increments' behaviour still holds. Establish the verification command once, run it every increment. An increment without a green check is just a chunk of a big bang wearing increments' clothes.
4. Migrate parallel, then cut over, then remove. For replacements: build the new alongside the old → migrate consumers one-by-one (each migration an increment) → only when the old has zero callers, delete it (its own increment). The both-exist window feels untidy; it's what makes every step reversible.
5. When an increment goes red: fix or revert, within the increment. Never pile the next increment onto a broken state "to fix it all together" — that's the moment incremental discipline dies and the mystery diff is born. The whole point is that red has one suspect; keep it that way.
6. Size to risk. Load-bearing/unfamiliar territory: smaller steps, verify obsessively. Well-trodden mechanical work: bigger steps are fine. If you can't predict what an increment will break, it's too big — split it.

Output Format

Increment plan: [target end state]

| # | Increment (thin working slice) | Type | Verified by | Stoppable? |

|---|---|---|---|---|

| 1 | | refactor-only / behaviour | [command/check] | ship / pause / rollback point |

The both-exist window (if migrating): [what coexists between steps N–M, and the cutover order]

Standing verification: [the command run after every increment]

(during execution, per increment: what landed → verification result → next)

Quality Checks

• [ ] Every increment ends in a demonstrated working state — no "works once the rest lands"
• [ ] No increment mixes refactoring with behaviour change
• [ ] The same verification ran green after each increment
• [ ] Any increment could serve as a stopping point without leaving wreckage
• [ ] Red states were fixed or reverted before the next increment began

Anti-Patterns

• [ ] Do not slice by layer — horizontal slices defer all verification to the end, which is the big bang with extra commits
• [ ] Do not "keep going" on a red state — stacking onto broken is how one bug becomes an archaeology dig
• [ ] Do not skip verification on 'trivial' increments — the trivial one is statistically where it breaks
• [ ] Do not delete the old path in the same increment as the last migration — cutover and removal are separate, reversible steps
• [ ] Do not let increments shrink into commit-theatre (40 one-line steps) — an increment is sized by verifiable meaning, not by smallness itself