Pilot Slice Branch Workflow — Claude Code Guide

Pilot slice: the smallest unit of migration execution

A pilot is not “half of a migration,” but a bounded check of a specific source-to-target hypothesis. Choose one endpoint, job, adapter, or other observable flow for which you can name inputs, outputs, dependencies, owner, and stop condition.

Separate migration execution into preparation, pilot, verification, and decision. Before the pilot, have migration discovery, compatibility assumptions, and a rollback path; otherwise a small diff creates a small but unpredictable risk.

Branch and worktree as boundary controls

Step	What to record	Why
Baseline	revision, clean/known diff, available checks	have a comparison point
Branch	separate name and one pilot scope	do not mix migration with feature work
Worktree	isolated path, owner, and cleanup rule	reduce overlap between parallel changes
Review	diff, affected paths, risk, and evidence	stop scope drift before merge
Decision	GO, HOLD, NARROW, or ROLLBACK	make the result explicit

Entry and exit gates for a pilot slice

Describe the migration hypothesis and bounded affected area in the task spec and migration plan.
Create a baseline revision and branch/worktree; do not mix unrelated changes.
Check that the rollback trigger, owner, and checkpoint are known before the first edit.
Perform only the agreed slice and collect the diff, focused checks, and behavior evidence.
Choose GO, HOLD, NARROW, or ROLLBACK; expanding scope requires a new decision.

When to stop a pilot

the source baseline cannot be reproduced or a critical input remains Unknown;
an undescribed data-format, configuration, or side-effect change is found;
the behavior comparison has no observable oracle or reveals a discrepancy;
rollback cannot return code and state to a defined safe point;
the diff leaves the bounded slice or requires an unapproved dependency upgrade.