| name | incremental-implementation |
| description | Implements features in thin, verifiable vertical slices instead of one large change. Use when implementing any change that touches more than one file, when adding a new feature, or any time the work could be split into multiple commits. |
Incremental Implementation
Overview
Ship thin vertical slices. Each slice does one observable thing end-to-end,
includes its own test, and leaves the system in a working state. Big-bang
implementations are the most common source of unreviewable changes,
regression bugs, and rollback nightmares.
When to Use
- Any change touching more than 2 files
- Adding a new feature, API endpoint, or UI component
- Migrating data or behaviour
- Replacing or extracting a module
When NOT to use: Single-file typo fixes, dependency bumps, config-only changes.
Process
-
Identify the smallest end-to-end slice. Not the smallest file change —
the smallest user-visible slice. "Add a button that calls a stub
endpoint that returns 200" is a slice. "Add a button" alone is not.
-
Implement the slice. Use feature flags or safe defaults so the new
code path is off in production until you flip it.
-
Test the slice. Write the test before or alongside the code (see
test-driven-development). If the slice has no test, it is not done.
-
Verify locally. Run the relevant test command. Check the build still
passes. For UI work, screenshot before and after.
-
Commit the slice atomically. One concept per commit. The commit
message names the slice, not the file list.
-
Move to the next slice. Do not bundle slices "because they're related"
— they belong in separate commits.
Common Rationalizations
| Rationalization | Reality |
|---|
| "These three changes are too small to commit separately" | Three small commits are easier to review and revert than one medium commit. |
| "Splitting it would mean writing the same setup twice" | Test setup duplication is fine (DAMP). Production code duplication is not. |
| "I'll commit it all at the end" | At the end you have no idea what's working and what isn't. Commit each slice as it lands. |
| "Feature flags add complexity" | A feature flag is cheaper than a revert under a production incident. |
Red Flags
- A single commit changes >300 lines of source (tests don't count toward this)
- The change can't be summarized in one imperative sentence
- The PR description lists more than 3 bullet points of "what changed"
- Tests were added "afterwards" rather than alongside the slice
- The change can't be safely deployed mid-rollout
Verification
After each slice, confirm:
