incremental-shipping

Incremental Shipping

Overview

A workflow for landing large changes as small, reversible increments. The skill exists because the most common shipping failure isn't a missing test or a bad deploy — it's a 1500-line PR that bundles a feature, a refactor, and a config change, takes three days to review, and lands with a regression nobody isolated. Incremental shipping splits that into thin vertical slices behind feature flags, plus a refactor-with-evidence section for behavior-preserving changes that need their own discipline (test deltas, perf measurements). Used after write-plan and test-first, before code-review-loop.

When to Use

• A feature plan has 5+ tasks and would otherwise ship as one PR
• A migration must run alongside existing code for a transition period
• A refactor changes structure but should preserve behavior; you need to prove it
• A change is risky enough that you want a kill switch in production

When NOT to Use

• The change is single-file and trivially reversible (git revert is enough)
• The change has no observable surface (internal-only refactor of a single function called by tests)
• An emergency hotfix where the cost of incrementality exceeds the cost of risk

Process

Step 1: Identify the vertical slice

Goal: Define the smallest change that delivers user-observable value (or preserves behavior, for refactors) and can ship on its own.

Inputs: A task or set of tasks from your plan.

Actions:

1. Ask: what's the smallest version of this change that a user could see, an API consumer could call, or a test could exercise? Not "the smallest piece of code" — the smallest value-delivering slice.
2. List what would be excluded from this slice: features, edges, polish. Excluded items become later slices.
3. The slice should be implementable in 1-3 PRs of <300 lines each.

Output: A slice definition: Slice 1: <what's included>; out of slice: <what's deferred>.

Step 2: Add the feature flag