incremental-migrationlisted

## Purpose Never attempt to migrate an entire codebase in a single step. Mega-commits are impossible to review and dangerous to merge. Migrate in verified, committed slices, tracking the remaining inventory to zero. ## When to Use - Replacing an API, library, or pattern with many call sites - A framework or major-version upgrade touches a wide surface area - A previous big-bang migration attempt stalled or was reverted ## Inputs - The "Old Way" and "New Way" definitions - The repo's test command ## Workflow 1. **Define the target pattern.** Clearly establish the "Old Way" and the "New Way". 2. **Build the inventory.** Make the migration measurable: ```bash git grep -ln "oldApiCall(" -- "src/" # files still on the Old Way git grep -c "oldApiCall(" -- "src/" | sort -t: -k2 -nr # hotspots first ``` 3. **Implement side-by-side.** Create the "New Way" implementation alongside the old one. Do not delete the old one yet. 4. **Migrate one vertical slice.** Pick exactly one feature, route, or component; update it to use the new pattern. Mechanical rewrites can be scripted per slice: ```bash # codemod sketch — scoped to one slice; review the diff before committing git grep -l "oldApiCall(" -- "src/feature-x/" | xargs sed -i "s/oldApiCall(/newApiCall(/g" git diff --stat # confirm the change stayed inside the slice ``` (For syntax-aware rewrites, AST codemod tools such as jscodeshift or comby are safer than sed, when availabl