Incremental Implementation

Incremental Implementation

Purpose

Stage: Implement (agent — per slice, inside a worktree). THE implementer workhorse. It applies test-driven-development as its rigid core loop and source-driven-development as a referenced discipline; the worktree isolation mechanism is owned by the orchestrator — implement runs in the worktree it is handed, it does not make its own.

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 / when to skip

• 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.

Inputs

Implement runs per slice, inside the worktree the orchestrator hands it (it does not create its own isolation; that is worktree, owned upstream). It consumes the Plan-stage contract cold and refuses to run if a load-bearing input is missing.

Two further inputs are read rather than required — both when the repo has them, and an absent one means the repo was never set up for it. Carry on in that case, and do not create either here; project-setup scaffolds both.

• docs/progress.md, the run record. It is where this slice's entry goes on the hand-run path (see The run record), and where a previous attempt at the same slice said what it ran and what came back.
• docs/lessons.md, the lessons record — read before you write the skeleton, not after the code is written. Each entry is a defect somebody root-caused, with the guard that would catch it coming back. The skeleton is where the decisions those entries are about get made, so a lesson read afterwards can only tell you what the rework is. You are reading for the entries that touch the area this slice builds in; a file with no entry near it costs one read and settles the question.

Disciplines it applies (consulted, not stages it consumes): test-driven-development (RED-GREEN-REFACTOR; test-first order is hook-enforced), source-driven-development (ground any framework/library decision in fetched official docs, as needed), debugging-and-error-recovery (five-step triage when a slice's tests break). It does not re-derive the plan, re-open the spec, or re-slice — the plan handed to it is already vertical.

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 the git-workflow skill 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.

Skeleton-First (stub → mock → wire → fill)

Within a vertical slice, build the skeleton end-to-end first, then fill it in — absorbed from cr-structure's build-order. Each step is independently observable:

• Read docs/lessons.md first, every slice. Before the stub, open the lessons record and look for entries touching the area this slice builds in. Every entry there is a defect this project already paid for once, and each names the guard that would catch it again — which is a decision about how to build, not a note to file afterwards. This is the only moment reading it changes anything: after the skeleton, the same entry costs a rewrite instead of a choice. A repo with no such file, or none near this area, costs one read.
• Read the design ref first (UI slices). Before the stub, open the prototype and contract named in the slice's Design ref. The skeleton is where layout, hierarchy and component boundaries get decided, and those are exactly what the prototype already decided — start from it and the fidelity check at Verify is a formality; start from a guess and it is a rewrite. A Design ref of — means no UI: skip straight to Stub.
• Stub — every layer the slice touches returns a hardcoded value; the end-to-end path already runs.
• Mock — swap stubs for mocks at the real boundaries; the shape of the data flows through.
• Wire — replace mocks with the real calls, one boundary at a time.
• Fill — handle the edge cases and error paths.

This is the antidote to horizontal building (all DB, then all API, then all UI), which yields code that does not work end-to-end until the last step and gives you nothing to debug from in between. The plan you were handed is already sliced vertically; skeleton-first is how you build each slice without silently re-horizontalizing it. The Increment Cycle's "Verify" step is the slice's checkpoint — a specific observable fact ("submitting the form shows the inline error"), never "it compiles".

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:

// 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 `npm test` and `npm run build` 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:

• 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)
• Linting passes (npm run lint)
• The new functionality works as expected
• The change is committed with a descriptive message

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.

The run record

When a slice is run by hand — no orchestrator dispatched it, and you are working in the repository itself rather than in a worktree handed to you — append that slice's entry to docs/progress.md when the attempt finishes. One entry, in the shape the file's ## Entry shape section holds: the commands you ran in the form you ran them, their real output, the files that changed, what was not run and why, and any follow-ups.

Inside an orchestrated run you are not the writer. The orchestrator opened a stub for this slice before dispatching you and completes it at the TERMINAL barrier, in the checkout it holds. You are inside a worktree, and a worktree is a branch that may never be merged — an entry appended there succeeds, reports success, and reaches no reader on the main line. Hand your commands and their output back instead; the orchestrator writes them into the entry it already owns. The two cases are told apart by one fact you already have: were you handed a worktree? Handed one → return the evidence. Working in the repository → append.

Three things about the entry, each of which someone gets wrong:

• One entry for the attempt, not one per increment. A thin slice is many increments by design, and an entry per increment buries the slice it was meant to describe. If a Verify pass ran on this attempt, its commands and output belong in this same entry — quality-verification never writes its own.
• Append only. An earlier entry is never edited, re-worded, re-dated, re-ordered, or removed, not even the one recording the failure this attempt fixed. A second attempt writes a second entry. An attempt to change an existing one is a STOP: the work ends there, and the violation is reported naming the entry and what would have changed. Refusing quietly reads as a silent success, and the previously recorded text stays readable in full either way.
• No state, no gate, no owner. STATE.md says which stage the slice is at and who acts next. This file says what ran. One question with two answers is one answer too many.

Two lines nothing enforces, and they are the reason the file is worth keeping. Never write that a command was run when it was not — put it under "Not run" with the reason, and write that line even when nothing was skipped. And withhold any credential that appears in output, saying that you withheld it rather than dropping the line silently. No hook and no CI checks either one.

The lesson a slice hands back

docs/lessons.md is the defect record. You read it before the skeleton and you never write it — and you are still the middle of that record's chain, because you are the slice's terminal. Whatever leaves this slice leaves on the hand-back you make to the orchestrator.

debugging-and-error-recovery is the discipline you reach for when a slice's tests break, and root-causing a defect is what obliges an entry. That skill authors one — every field filled, the guard named — and then meets the wall The run record above describes, for the same reason and told apart by the same fact: it is running in the worktree you were handed, so an append there lands on a branch that may never merge. It hands the finished entry back to you instead, and says it is still owed.

Carry it out, and name it as still owed, alongside the commands and their output you return for the run record. The orchestrator carries it into docs/lessons.md at the TERMINAL barrier, in the checkout it holds — the one place a handed-back entry reaches the main line. Its guard against a dropped one fires on a slice that handed an entry back, so an entry you never name creates no condition for that guard to test. Handed back silently it reads as done, and nothing downstream re-reports it.

Carrying is not authoring, and the red flag against appending still holds exactly as written. You do not open that file, fill a field, or turn a defect you fixed into an entry of your own — the record has two authors and you are neither. Carrying touches no file at all: the entry arrives finished and rides out on your return value, the way a command's output does. One author, one courier, one append.

Handed a worktree → return the entry. Working in the repository itself → there is nothing to carry, because debugging-and-error-recovery appends it where a reader will find it. A repository that keeps no docs/lessons.md was never set up for one; say so and carry on.

Rationalizations

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
• Writing a skeleton without having opened docs/lessons.md — the entries there are decisions about how to build, and read after the skeleton they are a post-mortem of your own work
• Appending to docs/lessons.md — you read that record and never write it, including when a Critical: review finding was routed back here and you fixed it without invoking debugging-and-error-recovery. Fixing a defect decides who fixed it, not who records it: a defect you root-caused is debugging-and-error-recovery's entry, and a Critical review finding is recorded by the re-review round that finds it closed. This flag is about authorship and reaches nothing else. Returning an entry that skill handed you finished is carrying, not writing — it opens no file — and The lesson a slice hands back is where that is required of you
• Returning from a slice without naming an entry debugging-and-error-recovery handed you as still owed — the orchestrator's guard fires on a slice that handed one back, so an unnamed entry leaves it nothing to catch. The lesson dies at the slice boundary, and no later stage re-reports it
• Writing UI in a slice whose Design ref names a prototype you never opened — Verify grades fidelity to that file, so a first look at it after the code is written is a rewrite waiting to happen
• Editing docs/design.md so the built surface matches it — the decided look is an oracle Verify grades inherited axes against, and it carries no signature of its own to protect it. Moving it to clear a design gate is gate-erosion → HALT. A slice reads that file; it never writes it.
• Appending to docs/progress.md from inside a worktree the orchestrator handed you — that write lands on a branch that may never merge and reaches no reader, while reporting success.
• Finishing a hand-run slice without an entry, or writing one that asserts a check passed with neither its output nor a "Not run" line behind it.
• Editing, re-wording, re-dating, re-ordering, or removing an entry already in docs/progress.md → STOP, and report the violation naming the entry and what would have changed. Append a new entry instead.
• Pasting a token, key, or password into an entry — withhold the value and say you withheld it.

Verification (ending criteria)

After completing all increments for a task:

• 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

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, the standing bar every increment clears regardless of the task. See references/definition-of-done.md.

Outputs & handoff contract

• Emits: a diff on the slice's worktree branch — the implemented slice as a sequence of atomic, individually-tested commits (code + the tests that prove it). This is the artifact quality-verification (Verify) consumes cold, alongside the running app and acceptance.md.
• Stable guarantees the consumer depends on:
  • The diff stays inside the slice's declared Regression surface (from plan.md). Narrowing or widening that surface to pass is a gate-erosion HALT, not a fix.
  • Tests land test-first (the test-driven-development order hook enforces it) and assert observable behavior, never mock calls (testing-strategy AP1).
  • The worktree is compilable and green at every increment checkpoint — never left broken between slices.
  • The slice diff stays within the ≤400 LOC cluster cap; if it cannot, the slice was mis-sliced — stop and surface, do not stretch the cap.
• Frozen-under-retry — safety rail 4 (references/safety-rails.md) governs acceptance.md, the RED tests, and the declared Regression surface, and it applies here on every rung of the escalation ladder, including the two that change the approach and the shape of the slice. Those change how the outcome is reached; the outcome is what acceptance.md says, on rung 1 and rung 4 alike. The way to green is to fix the impl, via debugging-and-error-recovery — no --no-verify, no hook edits, no SKIP_HOOKS.
• Read-only rather than frozen — docs/design.md, the repository's decided look (safety rail 4). A slice reads it and never writes it, retry or not.
• Appends to docs/progress.md — this slice's entry, only on the hand-run path: no orchestrator dispatched it and no worktree was handed over, so the append lands in the repository itself, where a reader will find it. Inside a run the orchestrator owns the entry and this skill returns its commands and their output instead — an entry appended from a worktree lands on a branch that may never merge and reaches nobody, which is the failure this split exists to avoid. One entry per attempt, carrying the commands as run, their real output, the files changed, and what was not run and why; append only, and no stage, state, gate, or owner in it. Full rule in The run record above.
• Hands back, on the same return and for the same reason, any lesson this slice owes: the finished entry debugging-and-error-recovery authored when it root-caused a defect here, returned unchanged and named as still owed. This skill is that entry's courier out of the worktree and nothing more — the orchestrator carries it into docs/lessons.md at the TERMINAL barrier, and this skill touches that file nowhere. On the hand-run path there is nothing to carry: the author already appended it in the repository itself. Full rule in The lesson a slice hands back above.
• STATE.md update: on a green slice checkpoint, flip the slice impl → verify (gate stays agent) and hand off to quality-verification. A slice that will not pass climbs the rungs of orchestrator's escalation ladder first — each one a different tactic, not another pass at the last one — and only a slice that has spent them within the bounded rounds (3 implement→verify→review cycles) is flipped impl → halted with its gate flipped agent → you. That is the failure-escalation path, the only place a human gate survives the autonomous run, and it is where a slice arrives after four different repairs rather than four identical retries.
• Consumer: quality-verification (Verify). Change the shape of what you emit → update quality-verification in the same commit.