Incremental Implementation

Incremental Implementation

Build in small, verified increments. Do not let work sprawl.

This skill is the execution discipline after a direction or plan exists.

For coding-related work, load engineering-principles before this skill. This skill applies those defaults through small slices and frequent evidence.

engineering-principles
        │
        ▼
planning-implementation / clear task
        │
        ▼
incremental-implementation  (you are here)
        │
        ├── choose next slice
        ├── implement only that slice
        ├── run fast feedback checks
        ├── behavior verification
        │     ├── high-level-testing-strategy  (if approach is unclear)
        │     ├── test-driven-development      (for automated verification)
        │     └── manual-testing               (for runtime verification)
        ├── doing-code-review                  (when warranted)
        └── verification-before-completion     (before success claims)

When To Use

Use this when:

• implementing a multi-file change
• executing a task from a written plan
• refactoring behavior or boundaries
• building a feature that could sprawl beyond one focused edit
• you are tempted to write a large amount of code before checking it

Skip this for tiny single-file edits where the scope is already obvious.

The Increment Cycle

┌──────────────────────────────────────────────┐
│ Pick smallest useful slice                   │
│        │                                     │
│        ▼                                     │
│ Implement only that slice                    │
│        │                                     │
│        ▼                                     │
│ Fast feedback: lint + typecheck / compile    │
│        │                                     │
│        ├── fails → fix / debug / escalate    │
│        │                                     │
│        ▼                                     │
│ Bigger checkpoint: tests or manual check     │
│        │                                     │
│        └── passes → next slice or handoff    │
└──────────────────────────────────────────────┘

For each slice:

1. Pick the smallest useful piece of work.
2. Implement only that piece.
3. Run fast feedback checks soon: lint, typecheck, compile, or equivalent.
4. Run tests or manual verification at meaningful checkpoints.
5. Stop, escalate, or continue based on evidence.

Slicing Strategies

Vertical Slices Preferred

In existing system, build one complete behavior path at a time.

Slice 1: Create task
  DB/model + API/service + minimal UI/CLI path
  -> user can create a task

Slice 2: List tasks
  query + API/service + minimal UI/CLI path
  -> user can see tasks

Slice 3: Edit task
  update path + validation + UI/CLI affordance
  -> user can modify tasks

Vertical slices keep every increment useful and testable.

Contract-First Slices For Big Greenfield Work

For large greenfield features or separate frontend/backend work, contract-first slicing can be better than a premature vertical path.

Slice 0: Define contract
  types / API shape / schema / generated client boundary

Slice 1a: Backend implements contract
  service + endpoint + contract/integration tests

Slice 1b: Frontend implements against contract
  typed client / mock server / fixture data

Slice 2: Integrate end-to-end
  real backend + real frontend + critical flow check

Use this when teams, agents, or codebases need to work in parallel without guessing each other's shapes.

Risk-First Slices

If one assumption could invalidate the whole plan, prove it early.

Slice 1: Prove WebSocket connection survives reconnect
Slice 2: Build real-time updates on the proven transport
Slice 3: Add offline behavior and UI polish

For the risky slice, use prototype-first, or try doubt-early if it fails, or revisit the plan instead of building around uncertainty.

Feedback Cadence

Agents do not see compiler and linter feedback continuously the way humans do. Run fast checks more often than full tests.

For tiny scripts or simple changes, manual verification may be enough. For maintained applications, prefer automated checks when available.

Do not repeat the same successful command for reassurance if no code changed since the last run. Run it again after the next relevant edit.

Scope Discipline

Touch only what the slice requires.

IN SCOPE
  Code needed for this slice
  Tests or checks proving this slice
  Tiny adjacent cleanup only when required by the change

OUT OF SCOPE
  Drive-by refactors
  Import reformatting in unrelated files
  Removing comments you do not understand
  Modernizing syntax while only passing through
  Adding features because they seem useful

If you notice unrelated problems, record them instead of fixing them silently.

NOTICED BUT NOT TOUCHING:
  - src/auth/session.ts has duplicated validation unrelated to this task
  - dashboard query could be paginated later

Simplicity Within Architecture

Prefer the simplest approach that fits the plan, existing architecture, and expected evolution.

This does not mean avoiding architecture. It means avoiding unearned architecture.

Plan or existing architecture says event-driven producer/consumer flow?
  -> Use the event bus or event pattern deliberately.

Plan does not call for eventing and this is a one-time local action?
  -> Use a direct function call.

Existing project uses factories for component registration?
  -> Follow that pattern if this belongs there.

One-off component with no expected variation?
  -> Do not invent a generic factory.

If plan is not certain enough about architecture, you may use architecting-changes. If the plan specifies only behavior and not structure, follow existing codebase patterns and choose the simplest maintainable implementation.

Ask the architecture question when the choice matters:

Will this evolve independently later?
Will more callers or variants appear soon?
Does this boundary prevent invalid states or dependency leaks?
Is this commodity infrastructure that a framework should own?

If the answer is no, keep it local and direct.

Executing A Written Plan

When a plan exists, treat it as input to execute thoughtfully, not a script to follow blindly.

Read task
  │
  ├── clear and realistic? -> execute one slice
  │
  ├── unclear?             -> clarify or escalate
  │
  ├── seems wrong?         -> doubt-early / plan validation
  │
  └── blocked?             -> isolate blocker, delegate/fix/escalate

Important practice: review the plan critically before and during execution.

Blockers And Escalation

Do not force through blockers. A blocker means the current plan, environment, or slice boundary may be wrong.

Escalation does not always mean asking the human immediately. Depending on the workflow level, it can mean:

• report to the higher-level orchestrator
• run doubt-early on the plan
• dispatch a focused subagent to investigate a build/test blocker
• pivot into systematic-debugging
• ask the human when requirements or priorities are genuinely missing

Working With Agents

This skill can be used at multiple levels:

Main agent on small/medium task
  -> uses incremental implementation directly

Low-level subagent on delegated task
  -> uses it inside the assigned slice only

Higher-level orchestrator
  -> uses it to define slice boundaries and verification cadence

Subagents should not silently expand their slice. If a delegated slice is wrong or blocked, report that precisely instead of improvising a larger plan.

For plan-driven execution with delegated implementation tasks, use executing-plans-with-subagents. For parallel fan-out decisions, use when-and-how-to-run-parallel-agents. For isolation, commits, and handoff, use git-workflow.

Related Skills

Common Mistakes

Completion Handoff

After a slice or task:

Report:
  - what slice changed
  - what checks ran
  - what remains
  - blockers or follow-ups

For multi-slice work, move to the next slice only when the current slice has fresh evidence appropriate to its size. For final completion claims, use verification-before-completion.