Phased implementation

--- name: incremental-implementation description: 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. --- # 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. ## The Increment Cycle `` ┌──────────────────────────────────────┐ │ │ │ Implement ──→ Test ──→ Verify ──┐ │ │ ▲ │ │ │ └───── Commit ◄─────────────┘ │ │ │ │ │ ▼ │ │ Next slice │ │ │ └──────────────────────────────────────┘ ` For each slice: 1. **Implement** the smallest complete piece of functionality 2. **Test** : run the test suite (or write a test if none exists) 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 ### 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: ``ty