Incremental Implementation

1---2name: incremental-implementation3description: Delivers changes incrementally. Use when implementing any feature or change that touches more than one file. Use 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.4---5 6# Incremental Implementation7 8## Overview9 10Build 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.11 12## When to Use13 14- Implementing any multi-file change15- Building a new feature from a task breakdown16- Refactoring existing code17- Any time you're tempted to write more than ~100 lines before testing18 19**When NOT to use:** Single-file, single-function changes where the scope is already minimal.20 21## The Increment Cycle22 23```24┌──────────────────────────────────────┐25│                                      │26│   Implement ──→ Test ──→ Verify ──┐  │27│       ▲                           │  │28│       └───── Commit ◄─────────────┘  │29│              │                       │30│              ▼                       │31│          Next slice                  │32│                                      │33└──────────────────────────────────────┘34```35 36For each slice:37 381. **Implement** the smallest complete piece of functionality392. **Test** — run the test suite (or write a test if none exists)403. **Verify** — confirm the slice works as expected (tests pass, build succeeds, manual check)414. **Commit** -- save your progress with a descriptive message (see `git-workflow-and-versioning` for atomic commit guidance)425. **Move to the next slice** — carry forward, don't restart43 44## Slicing Strategies45 46### Vertical Slices (Preferred)47 48Build one complete path through the stack:49 50```51Slice 1: Create a task (DB + API + basic UI)52    → Tests pass, user can create a task via the UI53 54Slice 2: List tasks (query + API + UI)55    → Tests pass, user can see their tasks56 57Slice 3: Edit a task (update + API + UI)58    → Tests pass, user can modify tasks59 60Slice 4: Delete a task (delete + API + UI + confirmation)61    → Tests pass, full CRUD complete62```63 64Each slice delivers working end-to-end functionality.65 66### Contract-First Slicing67 68When backend and frontend need to develop in parallel:69 70```71Slice 0: Define the API contract (types, interfaces, OpenAPI spec)72Slice 1a: Implement backend against the contract + API tests73Slice 1b: Implement frontend against mock data matching the contract74Slice 2: Integrate and test end-to-end75```76 77### Risk-First Slicing78 79Tackle the riskiest or most uncertain piece first:80 81```82Slice 1: Prove the WebSocket connection works (highest risk)83Slice 2: Build real-time task updates on the proven connection84Slice 3: Add offline support and reconnection85```86 87If Slice 1 fails, you discover it before investing in Slices 2 and 3.88 89## Implementation Rules90 91### Rule 0: Simplicity First92 93Before writing any code, ask: "What is the simplest thing that could work?"94 95After writing code, review it against these checks:96- Can this be done in fewer lines?97- Are these abstractions earning their complexity?98- Would a staff engineer look at this and say "why didn't you just..."?99- Am I building for hypothetical future requirements, or the current task?100 101```102SIMPLICITY CHECK:103✗ Generic EventBus with middleware pipeline for one notification104✓ Simple function call105 106✗ Abstract factory pattern for two similar components107✓ Two straightforward components with shared utilities108 109✗ Config-driven form builder for three forms110✓ Three form components111```112 113Three 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.114 115### Rule 0.5: Scope Discipline116 117Touch only what the task requires.118 119Do NOT:120- "Clean up" code adjacent to your change121- Refactor imports in files you're not modifying122- Remove comments you don't fully understand123- Add features not in the spec because they "seem useful"124- Modernize syntax in files you're only reading125 126If you notice something worth improving outside your task scope, note it — don't fix it:127 128```129NOTICED BUT NOT TOUCHING:130- src/utils/format.ts has an unused import (unrelated to this task)131- The auth middleware could use better error messages (separate task)132→ Want me to create tasks for these?133```134 135### Rule 1: One Thing at a Time136 137Each increment changes one logical thing. Don't mix concerns:138 139**Bad:** One commit that adds a new component, refactors an existing one, and updates the build config.140 141**Good:** Three separate commits — one for each change.142 143### Rule 2: Keep It Compilable144 145After each increment, the project must build and existing tests must pass. Don't leave the codebase in a broken state between slices.146 147### Rule 3: Feature Flags for Incomplete Features148 149If a feature isn't ready for users but you need to merge increments:150 151```typescript152// Feature flag for work-in-progress153const ENABLE_TASK_SHARING = process.env.FEATURE_TASK_SHARING === 'true';154 155if (ENABLE_TASK_SHARING) {156  // New sharing UI157}158```159 160This lets you merge small increments to the main branch without exposing incomplete work.161 162### Rule 4: Safe Defaults163 164New code should default to safe, conservative behavior:165 166```typescript167// Safe: disabled by default, opt-in168export function createTask(data: TaskInput, options?: { notify?: boolean }) {169  const shouldNotify = options?.notify ?? false;170  // ...171}172```173 174### Rule 5: Rollback-Friendly175 176Each increment should be independently revertable:177 178- Additive changes (new files, new functions) are easy to revert179- Modifications to existing code should be minimal and focused180- Database migrations should have corresponding rollback migrations181- Avoid deleting something in one commit and replacing it in the same commit — separate them182 183## Working with Agents184 185When directing an agent to implement incrementally:186 187```188"Let's implement Task 3 from the plan.189 190Start with just the database schema change and the API endpoint.191Don't touch the UI yet — we'll do that in the next increment.192 193After implementing, run `npm test` and `npm run build` to verify194nothing is broken."195```196 197Be explicit about what's in scope and what's NOT in scope for each increment.198 199## Increment Checklist200 201After each increment, verify:202 203- [ ] The change does one thing and does it completely204- [ ] All existing tests still pass (`npm test`)205- [ ] The build succeeds (`npm run build`)206- [ ] Type checking passes (`npx tsc --noEmit`)207- [ ] Linting passes (`npm run lint`)208- [ ] The new functionality works as expected209- [ ] The change is committed with a descriptive message210 211## Common Rationalizations212 213| Rationalization | Reality |214|---|---|215| "I'll test it all at the end" | Bugs compound. A bug in Slice 1 makes Slices 2-5 wrong. Test each slice. |216| "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. |217| "These changes are too small to commit separately" | Small commits are free. Large commits hide bugs and make rollbacks painful. |218| "I'll add the feature flag later" | If the feature isn't complete, it shouldn't be user-visible. Add the flag now. |219| "This refactor is small enough to include" | Refactors mixed with features make both harder to review and debug. Separate them. |220 221## Red Flags222 223- More than 100 lines of code written without running tests224- Multiple unrelated changes in a single increment225- "Let me just quickly add this too" scope expansion226- Skipping the test/verify step to move faster227- Build or tests broken between increments228- Large uncommitted changes accumulating229- Building abstractions before the third use case demands it230- Touching files outside the task scope "while I'm here"231- Creating new utility files for one-time operations232 233## Verification234 235After completing all increments for a task:236 237- [ ] Each increment was individually tested and committed238- [ ] The full test suite passes239- [ ] The build is clean240- [ ] The feature works end-to-end as specified241- [ ] No uncommitted changes remain