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.

Instructions

The Increment Cycle

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 (tests pass, build succeeds)
4. Commit — save progress with a descriptive message
5. Move to the next slice

Slicing Strategies

Vertical Slices (Preferred) — Build one complete path through the stack:

Slice 1: Create a task (DB + API + basic UI)  → User can create a task
Slice 2: List tasks (query + API + UI)         → User can see their tasks
Slice 3: Edit a task (update + API + UI)       → User can modify tasks
Slice 4: Delete a task (delete + API + UI)     → Full CRUD complete

Contract-First Slicing — When backend and frontend develop in parallel:

Slice 0: Define API contract (types, interfaces, OpenAPI spec)
Slice 1a: Backend against the contract + API tests
Slice 1b: Frontend against mock data matching the contract
Slice 2: Integrate and test end-to-end

Risk-First Slicing — Tackle the riskiest piece first:

Slice 1: Prove the WebSocket connection works (highest risk)
Slice 2: Build real-time updates on the proven connection
Slice 3: Add offline support and reconnection

Implementation Rules

Simplicity First: Before writing code, ask "What is the simplest thing that could work?"

✗ 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

Scope Discipline: Touch only what the task requires. Don't "clean up" adjacent code, refactor unrelated imports, or add features not in the spec.

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?

One Thing at a Time: Each increment changes one logical thing. Don't mix a new component, a refactor, and a build config change in one commit.

Keep It Compilable: After each increment, the project must build and existing tests must pass.

Feature Flags for Incomplete Features:

const ENABLE_TASK_SHARING = process.env.FEATURE_TASK_SHARING === 'true';
if (ENABLE_TASK_SHARING) {
  // New sharing UI — merged but not exposed
}

Rollback-Friendly: Each increment should be independently revertable. Prefer additive changes; keep modifications minimal and focused.

Examples

Directing an Agent

"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 `npm test` and `npm run build` to verify
nothing is broken."

Increment Checklist

After each increment:

• The change does one thing and does it completely
• All existing tests still pass (npm test)
• The build succeeds (npm run build)
• Type checking passes (npx tsc --noEmit)
• The new functionality works as expected
• The change is committed with a descriptive message

Guidelines

Common Rationalizations

Red Flags

• More than 100 lines written without running tests
• Multiple unrelated changes in a single increment
• "Let me just quickly add this too" scope expansion
• Build or tests broken between increments
• Building abstractions before the third use case demands it
• Touching files outside the task scope "while I'm here"

Verification

After completing all increments:

• Each increment was individually tested and committed
• The full test suite passes
• The build is clean
• The feature works end-to-end as specified
• No uncommitted changes remain