Incremental Implementation
Overview
Build in thin vertical slices — implement one piece, test it, verify it, then expand. Avoid implementing an entire feature in one pass. Each increment should leave the system in a working, testable state. This is the execution discipline that makes large features manageable.
When to Use
- Implementing any multi-file change
- Building a new feature from a task breakdown
- Refactoring existing code
- Any time you're tempted to write more than ~100 lines before testing
When NOT to use: Single-file, single-function changes where the scope is already minimal.
Before You Start: Branch Setup
Before any implementation begins, use the AskUserQuestion tool to confirm branch setup — never create a branch silently, even when the answer seems obvious.
- Check whether
devexists (locally or on the remote). If it does, fetch and pull it to make sure it's current before branching from it — a feature branch cut from a stale localdevsilently misses whatever's landed since. - Ask via
AskUserQuestion:- If
devexists: propose creating a feature branch fromdev(pulled to latest) — confirm before creating it, don't assume yes. - If
devdoesn't exist: say so explicitly in the same ask ("devbranch not found") and ask which branch to use instead, rather than guessingmainor any other default.
- If
- Create the feature branch only after that confirmation comes back.
Never run git commit when the work is done — this applies to the whole increment cycle below, not just the branch-setup step. Draft commit messages and propose them; leave the actual commit to the user unless they've explicitly asked you to commit in that session.
The Increment Cycle
┌────────────────────────────────────────────┐
│ │
│ Implement ──→ Test ──→ Verify ──┐ │
│ ▲ │ │
│ └───── Propose commit ◄─────┘ │
│ │ │
│ ▼ │
│ More slices? ──yes──→ Next slice │
│ │ │
│ no │
│ ▼ │
│ Run code-simplification (mandatory, │
│ not a checkbox — scoped to this task's │
│ diff only) — hold its report, no pause │
│ │ │
│ ▼ (same run, no stop/ask) │
│ Run quality-assurance (mandatory, │
│ not a checkbox) │
│ │ │
│ ▼ │
│ Show Simplification Report + │
│ Verification Report together │
│ │ │
│ ▼ │
│ Ask: run code review? (optional, │
│ via AskUserQuestion) ──no──→ task is done│
│ │ │
│ yes │
│ ▼ │
│ Run code-review │
│ │ │
│ ▼ │
│ Findings? ──none──→ task is done │
│ │ │
│ some │
│ ▼ │
│ Ask: fix Blockers / Blockers+Warnings / │
│ fix everything / fix nothing │
│ (via AskUserQuestion) ──nothing──→ done │
│ │ │
│ Blockers/Warnings/Suggestions │
│ ▼ │
│ Fix via the normal Implement→Test→ │
│ Verify loop above ──→ re-run │
│ quality-assurance (regression check) │
│ │ │
│ ▼ │
│ task is done │
│ │
└────────────────────────────────────────────┘
For each slice:
- Check for an existing library before hand-writing new logic. Before implementing anything that falls into a category
references/library-reuse.mdcovers (date/time, validation, HTTP, auth, ORM, retries, and more), check that reference for this project's actual language/ecosystem (Node/TS, Python, C#/.NET, Go, and more — not a JS/TS default out of habit). If it names a proven library already in the project's dependencies, use it instead of hand-rolling the logic. If it names one not yet a dependency, that's a real decision — surface it rather than silently picking either side (adding a new dependency mid-slice, or hand-writing something a library already solves) — a quick note is enough for something low-stakes,AskUserQuestionfor anything that adds a new dependency to the project. Skip this check only when the slice's logic genuinely isn't in a category that reference covers. - Implement the smallest complete piece of functionality
- Test — every slice gets a unit test, not just slices that "need" one; if the slice has real core logic (a calculation, a state transition, a validation rule), the test must assert its actual expected behavior, not just that it runs without error (see
test-driven-development's core-component coverage) — that's what catches a regression later, not just now. That coverage must span every scenario type that genuinely applies to the slice's core logic — happy path, edge cases (boundary/empty/null/optional-absent), error handling (invalid/malformed input), and fix/regression confirmation when the slice exists to fix something — not just whichever one was fastest to write. Run the full suite alongside it. - Verify — confirm the slice works as expected: the full test suite actually runs and passes (not just the tests that look related to this slice), the project's build/compile step succeeds, and its linter (and type checker, where the language has one) passes — using whatever commands this project actually defines (its
package.jsonscripts,Makefile,pyproject.toml/tox.ini,.csprojtargets, etc.), never assumed to benpm test/npm run buildby habit — plus a manual check. Build and lint passing is not a substitute for the full test suite having actually run — a type checker frequently has its own blind spots (e.g. test/spec files excluded from the build's type-checking pass is a real, common gotcha), so code that's green on build+lint can still contain a runtime-only bug (a hand-written test fixture missing a field a real caller would always provide, for instance) that only the test suite's actual execution surfaces. Every slice re-runs the full suite — never only the subset of checks that seem relevant to what this particular slice touched. - Propose a commit — draft a descriptive message and tell the user the slice is ready (see
git-workflow-and-versioningfor atomic commit guidance). Never rungit commityourself — leave the actual commit to the user unless they've explicitly asked you to commit in this session. - Move to the next slice — carry forward, don't restart, and don't wait for the commit to happen first
When the last slice for this task is done, before running QA — run code-simplification over the task's diff. This is a compulsory part of the cycle, exactly like the quality-assurance gate below it — not an optional pass, not something to offer via AskUserQuestion, and not something to skip because the code already looks fine. It is, however, tightly scoped: the diff this task just produced, not the whole file or module it lives in (code-simplification's own "Scope to What Changed" principle). The point is to catch the complexity that accumulates naturally across several slices — a helper that made sense mid-implementation but is now redundant, a parameter nothing uses anymore, duplication between two slices that didn't exist when each was written alone — while the code is still fresh, before QA spends effort verifying a version that's about to be cleaned up anyway. code-simplification already carries its own safety net (a baseline check before starting, one change at a time with a revert-if-unclear rule, tests treated as out of scope to edit) — rely on that rather than re-deriving it here. If the pass finds nothing worth changing, say so and move on; it's not a step to pad with busywork.
code-simplification produces its own Simplification Report (a table of what was found, and whether it was simplified / kept as-is / reverted) — hold onto it and go straight into quality-assurance next, in the same run, with no pause in between. Finishing code-simplification is not a stopping point, not a checkpoint to ask the user anything at, and not a place to end the turn — it's the handoff from one mandatory step to the next, exactly like finishing one slice's Verify step flows straight into the next slice above. Don't surface the Simplification Report on its own and then wait; carry it forward and present it together with the Verification Report once QA is done (see below) — the two tables appear together, back-to-back, as a single end-of-cycle report, not the simplify table first with the workflow stopping before QA ever runs.
Immediately after code-simplification finishes — without stopping, without asking, in the same run — actually invoke the quality-assurance skill against the spec, and it must be genuinely live — a real server, real database, real authenticated user — not mocked tests or a suite that merely happens to be named "e2e." This is a mandatory action to take, not a box to mentally check off afterward: in practice, agents following this skill have skipped straight to declaring the task done with unit tests passing, and only run quality-assurance when the user notices and asks for it — and even then, have substituted mocked/unit-level tests for live verification without saying so. Don't let either be the trigger — run quality-assurance live yourself, unprompted, as the actual last step of the cycle. If full live verification is tedious to set up, quality-assurance's own graduated fallback applies (a lighter live check via curl/CLI or an automated test against the real dev server, offered via AskUserQuestion) — never downgrade straight to mocks on your own. Once QA's own Verification Report is ready, present it immediately after (or alongside) the held Simplification Report from the step before, so both tables land together in the same message rather than the Simplification Report having already been shown and the conversation having stalled before QA ran at all.
After quality-assurance finishes (pass or fail) — offer an optional code review, via AskUserQuestion. This is a separate, optional step, not part of the mandatory QA gate above: ask something like "QA is done. Run a code review pass over this work before finishing? (recommended, but optional)" with options to run it now or skip. If the user chooses to run it, invoke code-review against the full diff for this task (not just the last slice) and report its findings before declaring the task done. If the user skips, say so plainly and move on; don't ask twice or treat a skip as something to revisit later in the same task.
If the review ran and surfaced anything, ask how much of it to fix — via AskUserQuestion, as a single cumulative choice, not a separate question per finding. The review's own severities give the natural scope boundaries, so offer exactly these options (omit any tier the review found nothing in):
- Fix Blockers only
- Fix Blockers + Warnings
- Fix everything (Blockers + Warnings + Suggestions)
- Don't fix anything — leave the findings as reported
Whichever scope is picked, fix every finding within it the same way the rest of this task was built: through the normal Implement → Test → Verify loop above, one finding (or a tightly related group) treated like any other slice — not a bare patch applied outside that loop. Once the fixes are in, re-run quality-assurance live, the same way as before — this is a regression check, confirming the fixes didn't break anything the first QA pass already confirmed working, not a second independent QA run from scratch. Only then is the task actually done. If "don't fix anything" was picked, the task is done once the findings have been reported — don't fix silently and don't ask the fix-scope question twice for the same review.
Slicing Strategies
Vertical Slices (Preferred)
Build one complete path through the stack:
Slice 1: Create a task (DB + API + basic UI)
→ Tests pass, user can create a task via the UI
Slice 2: List tasks (query + API + UI)
→ Tests pass, user can see their tasks
Slice 3: Edit a task (update + API + UI)
→ Tests pass, user can modify tasks
Slice 4: Delete a task (delete + API + UI + confirmation)
→ Tests pass, full CRUD complete
Each slice delivers working end-to-end functionality.
Contract-First Slicing
When backend and frontend need to develop in parallel:
Slice 0: Define the API contract (types, interfaces, OpenAPI spec)
Slice 1a: Implement backend against the contract + API tests
Slice 1b: Implement frontend against mock data matching the contract
Slice 2: Integrate and test end-to-end
Risk-First Slicing
Tackle the riskiest or most uncertain piece first:
Slice 1: Prove the WebSocket connection works (highest risk)
Slice 2: Build real-time task updates on the proven connection
Slice 3: Add offline support and reconnection
If Slice 1 fails, you discover it before investing in Slices 2 and 3.
Implementation Rules
Rule 0: Simplicity First
Before writing any code, ask: "What is the simplest thing that could work?"
After writing code, review it against these checks:
- Can this be done in fewer lines?
- Are these abstractions earning their complexity?
- Would a staff engineer look at this and say "why didn't you just..."?
- Am I building for hypothetical future requirements, or the current task?
SIMPLICITY CHECK:
✗ Generic EventBus with middleware pipeline for one notification
✓ Simple function call
✗ Abstract factory pattern for two similar components
✓ Two straightforward components with shared utilities
✗ Config-driven form builder for three forms
✓ Three form components
Three similar lines of code is better than a premature abstraction. Implement the naive, obviously-correct version first. Optimize only after correctness is proven with tests.
Rule 0.5: Scope Discipline
Touch only what the task requires.
Do NOT:
- "Clean up" code adjacent to your change
- Refactor imports in files you're not modifying
- Remove comments you don't fully understand
- Add features not in the spec because they "seem useful"
- Modernize syntax in files you're only reading
If you notice something worth improving outside your task scope, note it — don't fix it:
NOTICED BUT NOT TOUCHING:
- src/utils/format.ts has an unused import (unrelated to this task)
- The auth middleware could use better error messages (separate task)
→ Want me to create tasks for these?
Rule 1: One Thing at a Time
Each increment changes one logical thing. Don't mix concerns:
Bad: One proposed commit that adds a new component, refactors an existing one, and updates the build config.
Good: Three separately proposed commits — one for each change (the user runs them, or asks you to).
Rule 2: Keep It Compilable
After each increment, the project must build and existing tests must pass. Don't leave the codebase in a broken state between slices.
Rule 3: Feature Flags for Incomplete Features
If a feature isn't ready for users but you need to merge increments:
// Feature flag for work-in-progress
const ENABLE_TASK_SHARING = process.env.FEATURE_TASK_SHARING === 'true';
if (ENABLE_TASK_SHARING) {
// New sharing UI
}
This lets you merge small increments to the main branch without exposing incomplete work.
Rule 4: Safe Defaults
New code should default to safe, conservative behavior:
// Safe: disabled by default, opt-in
export function createTask(data: TaskInput, options?: { notify?: boolean }) {
const shouldNotify = options?.notify ?? false;
// ...
}
Rule 5: Rollback-Friendly
Each increment should be independently revertable:
- Additive changes (new files, new functions) are easy to revert
- Modifications to existing code should be minimal and focused
- Database migrations should have corresponding rollback migrations
- Avoid deleting something in one commit and replacing it in the same commit — separate them
Working with Agents
When directing an agent to implement incrementally:
"Let's implement Task 3 from the plan.
Start with just the database schema change and the API endpoint.
Don't touch the UI yet — we'll do that in the next increment.
After implementing, run this project's test, build, and lint
commands to verify nothing is broken."
Be explicit about what's in scope and what's NOT in scope for each increment.
Increment Checklist
Resolve this project's actual commands first (never assume npm/tsc by habit) — check package.json scripts, a Makefile, pyproject.toml/tox.ini, .csproj targets, or whatever this ecosystem/project actually defines, the same way references/library-reuse.md's Step 0 resolves the ecosystem. After each increment, verify:
- The change does one thing and does it completely
- A unit test was added for this increment's new logic
- All existing tests still pass (this project's test command — e.g.
npm test,pytest,dotnet test,go test ./...) - The build/compile step succeeds (e.g.
npm run build,dotnet build,go build ./...; for a dynamically-typed language with no separate build step, this may just be the test command itself) - Type checking passes where the language has a separate step for it (e.g.
tsc --noEmit,mypy) - Linting passes (this project's configured linter — e.g.
npm run lint/eslint,ruff/flake8,dotnet format --verify-no-changes,golangci-lint run) - The new functionality works as expected
- A descriptive commit message has been proposed for the change (do not run
git commityourself — leave it to the user unless they've explicitly asked you to commit) - Once all slices for the task are done,
code-simplificationwas run over the task's diff beforequality-assurance— not skipped, and not run over the whole file/module beyond what this task touched
Note: Run each verification command after a change that could affect it. After a successful run, don't repeat the same command unless the code has changed since — re-running on unchanged code adds no information. This never means swapping the full test suite for a narrower set of checks that seem more relevant to the current slice (build + lint + only the tests for the area just touched) — build and lint do not execute the same code paths a unit test does, so a slice can be green on both while a test that was never re-run would have caught a real runtime bug. Every slice that changes code re-runs the full suite, not a hand-picked subset of it.
Common Rationalizations
| Rationalization | Reality |
|---|---|
| "I'll test it all at the end" | Bugs compound. A bug in Slice 1 makes Slices 2-5 wrong. Test each slice. |
| "This slice is too trivial for a unit test" | Trivial slices are where regressions hide longest — no one re-checks something assumed too simple to break. |
| "It's faster to do it all at once" | It feels faster until something breaks and you can't find which of 500 changed lines caused it. |
| "These changes are too small to commit separately" | Small commits are free. Large commits hide bugs and make rollbacks painful — propose them as separate commits even though the user runs the actual git commit. |
| "I'll add the feature flag later" | If the feature isn't complete, it shouldn't be user-visible. Add the flag now. |
| "This refactor is small enough to include" | Refactors mixed with features make both harder to review and debug. Separate them. |
| "Let me run the build command again just to be sure" | After a successful run, repeating the same command adds nothing unless the code has changed since. Run it again after subsequent edits, not as reassurance. |
| "Build, lint, and the integration tests for this area passed — that covers this slice" | Build and lint don't execute runtime logic the way a unit test does, and a type checker commonly has its own blind spots (test/spec files excluded from the build's type-checking pass is a real, common one) — a hand-written test fixture missing a field a real caller always provides can stay invisible to build+lint and only surface when the actual test runs. Re-run the full suite, not a subset chosen because it seemed relevant to this slice. |
| "All the unit tests pass, so the feature works" | Unit tests confirm the code does what the code does — they don't confirm it does what the spec asked for. Run quality-assurance for that. |
| "The code works, I'll skip the simplify pass and go straight to QA" | QA verifies behavior, not complexity — skipping simplification just means QA ends up verifying code that's about to need a second pass anyway. Run it first, while the diff is still fresh. |
| "I showed the Simplification Report, that's a natural place to pause and let the user react" | It isn't — code-simplification finishing is a handoff to quality-assurance, not a checkpoint. Hold the report and keep going in the same run; show both tables together once QA is done. |
| "I'll simplify the whole file while I'm in there" | code-simplification scopes to the task's diff, same as every other step here — broadening it mid-task is the same scope creep Rule 0.5 already forbids elsewhere. |
| "It's just a few lines, not worth checking library-reuse.md for" | A few hand-written lines today is exactly how a hand-rolled date parser, validator, or retry loop ends up duplicated across a codebase — the check costs one lookup, not a detour. |
| "I'll just add this npm package, it's an obvious choice" | Adding a dependency mid-slice is a real decision, not a formality — surface it (a quick note or AskUserQuestion, by stakes) rather than deciding it silently on the user's behalf. |
| "I'll just branch from dev without asking, it's the obvious choice" | Ask anyway — confirming before creating a branch costs one question and prevents working on the wrong base entirely. |
| "dev doesn't exist, I'll just use main" | Guessing a fallback base branch silently can put the feature on the wrong branch structure for this project — ask which branch to use instead. |
| "I tested that this slice rejects bad input, it's covered" | That's one scenario type. A slice's core logic needs happy path, edge cases, error handling, and fix/regression confirmation covered together, as each genuinely applies — not just whichever was fastest to write. |
| "QA passed, I'll skip offering the code review and just finish" | The review is optional for the user to decline, not for you to pre-decide on their behalf — always ask via AskUserQuestion once QA is done, even when everything's green. |
| "There's only one Blocker, I'll just fix it without asking" | The user decides the fix scope, not you — even an obvious one-line fix still goes through the AskUserQuestion scope choice first. |
| "I fixed the Blockers, no need to re-run QA, the fix was small" | Small fixes break things too. The re-run is what confirms the fix didn't regress what QA already proved worked — skipping it turns "confirmed fixed" into "probably fixed." |
Red Flags
- More than 100 lines of code written without running tests
- Multiple unrelated changes in a single increment
- "Let me just quickly add this too" scope expansion
- Skipping the test/verify step to move faster
- Build or tests broken between increments
- Large uncommitted changes accumulating
- Building abstractions before the third use case demands it
- Touching files outside the task scope "while I'm here"
- Creating new utility files for one-time operations
- Running the same build/test command twice in a row without any intervening code change
- A later slice verified with only build/lint/integration tests (or "the tests for this area"), with the full unit suite not actually re-run since an earlier slice
- A regression later traced to a runtime-only bug (a type-checker blind spot, a hand-written fixture missing a field) that the full test suite would have caught had it been re-run after the slice that introduced it
- Running
git commityourself without the user explicitly asking you to in that session - The feature declared done once unit tests pass, without running
quality-assuranceagainst the spec - Moving straight from the last slice to
quality-assurancewithout runningcode-simplificationover the task's diff first code-simplificationrun broader than this task's own diff (a whole file or module it merely lives in)code-simplification's Simplification Report not shown, or collapsed into a one-line summary instead of its full table- The Simplification Report shown on its own and the run stopping there, with
quality-assurancenot following immediately in the same run - The workflow pausing or asking a question between
code-simplificationfinishing andquality-assurancestarting - New logic hand-written for a category
references/library-reuse.mdcovers, with no check against it first - A new dependency added to the project mid-slice without surfacing it (a note or
AskUserQuestion, by stakes) quality-assurancerun against mocks or a suite merely named "e2e", reported as if it were genuinely live verification- A slice's core-logic test covering only one scenario type (e.g. only error/rejection handling) when happy path, edge cases, or fix confirmation genuinely applied too
- A feature branch created without asking first, or without pulling
devto latest before branching from it devmissing and a fallback branch picked silently instead of asked about- The task declared done right after
quality-assurancewith noAskUserQuestionoffer of a code review pass - A code review offered and accepted, then skipped or the findings never reported before declaring the task done
- Findings fixed without first asking which scope (Blockers only / +Warnings / everything / nothing) to fix
- Fixes applied as a bare patch instead of through the normal Implement → Test → Verify loop
quality-assurancenot re-run after findings were fixed, leaving the fix's effect on previously-passing behavior unconfirmed
Verification
Before starting:
- Branch setup was confirmed via
AskUserQuestionbefore any implementation began — not assumed - If
devexisted, it was pulled to latest before the feature branch was created from it - If
devdidn't exist, that was stated explicitly and an alternative base branch was asked for, not guessed
After completing all increments for a task:
- Each slice's new logic was checked against
references/library-reuse.mdbefore being hand-written, for any category that reference covers, and any new dependency it would add was surfaced rather than decided silently - Each increment was individually tested (a unit test was added, not just an existing-suite check) and left with a proposed commit message
- Each slice's core-logic test covers every scenario type that genuinely applies (happy path, edge cases, error handling, fix/regression confirmation) — not just the one type that was fastest to check
-
code-simplificationwas run over the task's diff beforequality-assurance— mandatory, scoped to this task's changes only -
code-simplification's Simplification Report was held, not shown in isolation, andquality-assurancestarted immediately afterward in the same run with no pause or question in between - The Simplification Report and the Verification Report were presented together, back-to-back, once QA finished — not the simplify table alone followed by the workflow stopping
- The full test suite actually ran (not just build/lint, and not just the tests for the area the last slice touched) and passes after every slice that changed code
- The build is clean
- Linting (and type checking, where the language has one) passes
- The feature works end-to-end as specified — run the
quality-assuranceskill live (real server, real database, real authenticated user) against the spec/acceptance criteria to confirm this with real evidence, not just unit tests passing and not mocks substituted for live verification - After
quality-assurancecompleted, an optional code review pass was offered viaAskUserQuestion— and if accepted,code-reviewwas actually run and its findings reported before declaring the task done - If the review surfaced any findings, a fix-scope choice (Blockers only / +Warnings / everything / nothing) was offered via
AskUserQuestionbefore fixing anything - Any accepted fixes went through the normal Implement → Test → Verify loop, and
quality-assurancewas re-run live afterward to confirm no regression - No unreviewed changes remain — the user has a summary and a proposed commit message for each increment; committing is theirs to do (or explicitly delegated to you)
See Also
code-simplification— mandatory pass over the task's diff after the last slice, beforequality-assurance; cleans up complexity that accumulated across slices while behavior stays fixedquality-assurance— the live/end-to-end check once all increments are complete; unit tests alone don't confirm the feature works against the speccode-review— the optional review offered viaAskUserQuestionafterquality-assurancefinishesreferences/library-reuse.md— the dependency check at the start of each slice: which proven library to reach for instead of hand-writing a solved problem, per ecosystemreferences/coding-patterns.md— structural patterns to apply while implementing each slice (clear main path, external systems behind a boundary, unrepresentable invalid states, decisions separated from actions, useful errors)review-findings.mdat the project's external output location (seereferences/external-output-paths.md) — check it before starting a task, if it exists; it's a running log of patterns code review has already flagged in this project, and repeating one is avoidable
