# Incremental Implementation > Delivers changes incrementally in thin, verifiable vertical slices. Use when implementing any feature or change that touches more than one file, or when picking up the next task from a plan. Use when rolling a change out behind a feature flag, when you're about to write a large amount of code at once, or when a task feels too big to land in one step. Use when an Epic parent todo indexes child tracks so implementation must move to a child worktree rather than building the epic in the parent checkout. - Skill: `tinyc0der/incremental-implementation` (Agent Skill) - Install (CLI): `npx skillmds@latest add tinyc0der/incremental-implementation` - Raw SKILL.md: https://api.skillmd.com/api/skills/tinyc0der/incremental-implementation/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - Author: tinyc0der (https://skillmd.com/u/tinyc0der) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/tinyc0der/incremental-implementation --- # 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. **Workflow notes:** For an active track, read `docs/tracks//notes.md` at phase entry or resume and update it when useful context changes or before handoff. Capture observations, tentative ideas, outcomes, blockers, and next actions with evidence links. Follow the memory-management running-note and document-metadata protocols; honor explicit read-only or file-scope limits and keep writes outside pinned verification or release targets. ## 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. ## The Increment Cycle ``` ┌──────────────────────────────────────┐ │ │ │ Implement ──→ Test ──→ Verify ──┐ │ │ ▲ │ │ │ └───── Commit ◄─────────────┘ │ │ │ │ │ ▼ │ │ Next slice │ │ │ └──────────────────────────────────────┘ ``` For each slice: If the active track is an initiative (`role: initiative`, or `docs/tracks//todo.md` indexes child track ids — even if leftover implementation tasks exist), do not implement those children here. Apply the [delivery fork](../using-agent-skills/SKILL.md#delivery-fork): open or resume the next unblocked child in its own linked worktree, using the allocated child track id (do not mint a second prefix). If the child's requirements are still a stub, complete its selected route's prerequisites first; Feature children run `spec-driven-development` then `planning-and-task-breakdown` there and stop. Run this skill only after the child's requirements and required task state are checked. `/build auto` on a parent advances the next child; it does not implement the epic. Check the combined PR against the track's outcome and boundaries before each new task. If scope has outgrown one focused review, return to `planning-and-task-breakdown`, preserve existing work, and split unmerged changes and remaining outcomes into sibling tracks. Each implementation track gets its own branch, linked worktree, and PR. A destructive migration contract requires a separate track and PR from the expand. Execute remaining slices within the current track's PR boundary and the user's authorized scope, preserving per-slice checks and commits. At that boundary, verify and hand off the PR before continuing authorized work in the next track's worktree; `/build auto` must not append the next track to this PR. If the user asks for one task or stepwise review, stop at that endpoint. A normal test failure enters debugging and re-verification; a human gate is needed only for unresolved material intent, missing authority/access, or consequential risk that cannot be contained and verified autonomously. Reuse the user's existing authorization for the plan and routine implementation choices. Multiple approaches alone do not require a question: choose within established intent and delegated judgment; ask with options and a recommendation when consequential trade-offs remain unresolved. Notify the user promptly in the active conversation about evidence of an active production outage, suspected compromise, or ongoing data loss, without waiting for complete diagnosis. Stop unsafe actions and continue authorized containment and fixes; notification grants no additional authority. Pause only work awaiting a required answer and continue safe independent work. 1. **Implement** the smallest complete piece of functionality 2. **Test** — apply `test-case-design-review`'s admission gate, add only the smallest missing behavioral case, then use `test-driven-development` for RED-GREEN-REFACTOR and run the focused suite; when no new case is warranted, record why and run the relevant existing or executable check 3. **Verify** — confirm the slice works as expected (tests pass, build succeeds, manual check) 4. **Commit** -- save your progress with a descriptive message (see `git-workflow-and-versioning` for atomic commit guidance) 5. **Move to the next slice** — carry forward, don't restart ## Slicing Strategies These strategies find delivery boundaries as well as smaller implementation steps. Distinct outcomes such as create, list, edit, and delete usually become separate tracks and PRs. Several commits may implement one outcome, but commit boundaries do not replace PR boundaries. Dependent tracks may use an explicit stacked base or wait for prerequisites to merge. ### 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 commit that adds a new component, refactors an existing one, and updates the build config. **Good:** Three separate commits — one for each change. ### 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: ```typescript // 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: ```typescript // 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 the repository's test and build commands to verify nothing is broken." ``` Be explicit about what's in scope and what's NOT in scope for each increment. ## Increment Checklist After each increment, verify with the repository's own commands (see the test-driven-development skill's Discover the Stack First section): - [ ] The change does one thing and does it completely - [ ] All existing tests still pass (the repository's test command: `npm test`, `./gradlew test`, `pytest`, ...) - [ ] Every new test protects a distinct material regression at the cheapest reliable layer; no test was added merely to give the increment a test - [ ] The build succeeds (the repository's build command) - [ ] Type checking passes, where the stack has one (`npx tsc --noEmit`, `mypy`, ...) - [ ] Linting passes (the repository's lint command) - [ ] The new functionality works as expected - [ ] The change is committed with a descriptive message - [ ] The combined PR still fits the current track's single outcome; new outcomes were moved to separate tracks **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. ## 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. | | "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. | | "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. | ## 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 - Implementing child features in an initiative parent worktree because `/build auto` was invoked on the parent - 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 ## Verification After completing all increments for a task: - [ ] Each increment was individually verified and committed; behavioral increments applied the test admission gate - [ ] The full test suite passes - [ ] The build is clean - [ ] The feature works end-to-end as specified - [ ] No uncommitted changes remain ## See Also Per-increment verification is the local check. Before declaring a task done, apply the project-wide Definition of Done as the final gate: acceptance criteria met, focused and regression tests pass, runtime behavior is demonstrated, lint/build/type checks pass when applicable, relevant documentation and safeguards are updated, and the increment is independently revertible. Optional whole-pack reference: `../../references/definition-of-done.md`.