Sweep: $ARGUMENTS

A migration is not a feature: the steps repeat, the risk is the tail — the sites your first search didn't find — and "done" is a property of the whole set, not of any one edit. So the discipline inverts the feature pipeline: inventory before any edit, a pilot before scale, verification per batch, and a final re-scan that must come back empty.

$ARGUMENTS describes the transform ("rename fetchUser → getUser", "replace moment with date-fns"). If empty, ask what to migrate and stop.

Phase 0 — Load profile

1. Read .claude/PROJECT.md — Commands (test, test:targeted, lint), Architecture (scope: which trees are app code vs vendored/generated). If missing or TEMPLATE, fall back to the root CLAUDE.md (always in context) when it carries the commands/architecture — note you're running without a kit profile; only if neither has them, STOP: run /bootstrap first.
2. Read the .claude/rules/* whose paths cover the touched trees — transformed code must land in house style, not just compile.

Phase 1 — Define the transform (before searching)

Pin the recipe as a contract:

• FROM → TO — one worked example pair (real code, before and after), the way a reviewer would want to see it. Ambiguity here multiplies by the site count.
• Mechanical vs judgment — state the rule for which sites are pure substitution and which need a human-style decision (changed semantics, error handling differences, incompatible signatures). Judgment sites are flagged and proposed, never auto-applied.
• Out of scope — generated files, vendored code, lockfiles, the old library's own tests.
• Stored as data? If the old name also lives outside the repo — status strings in rows, event or message type names, discriminators, routing keys, graph edge types — that half is a data migration, not a rename: route it to /rollout (expand/contract), and a clean re-scan does not close it.

Confirm the recipe with the user via AskUserQuestion if any of the three is uncertain.

Phase 2 — Inventory EVERY site (no edits yet)

Multi-modal, like /discover — one search angle always misses:

• Grep the symbol and its aliases (imports-as, re-exports, destructuring).
• Grep strings: log messages, config keys, docs, comments, test names mentioning it.
• Grep dynamic uses: reflection, string-built calls, serialized names in fixtures/data. Each dynamic site is a judgment site by definition and a rules/_generic/code.md finding — the migration is the moment to make it static.
• Glob file patterns the migration implies (e.g. every file importing the old library).
• In a typed stack, break it on purpose: rename or remove the old symbol and let the compiler enumerate the call sites grep missed, then restore. Untyped → say so and stay with search.

Produce the site inventory — the sweep's single source of truth. Write it to a file (scratchpad, or alongside the report at the Plans location) rather than only into the reply: it is the sole record of which of N sites are done, and a migration outlives the context window that held the chat. Each row carries its own status, so the table is the progress tracker — there is no second one to keep in sync.

| # | path:line | Kind (mechanical / judgment / string-doc) | Batch | Status (todo / done / judgment / deferred / exception) |

State the total count. If you bound the inventory in any way (scope, sampling), say what was excluded and why — a truncated inventory that reads as complete is how migrations ship half-done. For a large repo, delegate discovery angles to parallel read-only Explore agents over disjoint subtrees and merge their citations.

Phase 3 — Pilot batch (prove the recipe)

Transform 3–5 representative mechanical sites (include the ugliest one, not just the cleanest). Run test:targeted on the touched modules. Show the user the pilot diff and confirm the recipe holds. A recipe correction here rewrites the plan for hundreds of sites — that's the point of piloting. Do not proceed past a failing or unconfirmed pilot.

Phase 3½ — Write the tool, not the edits (large sweeps)

When the mechanical inventory exceeds ~30 sites, stop hand-editing: express the recipe as a codemod and let the pilot prove the program, not the prose.

• Prefer AST/structure-aware transformation over regex — whatever tool the stack rule packs or PROJECT.md name for this language (codemod frameworks, structural search-and-replace tools); regex only for trivial token renames with zero syntactic ambiguity.
• Build it in the scratchpad; run it against the Phase-3 pilot sites first and diff-review exactly as before. Use the tool's dry-run/diff mode as the review surface.
• Why this beats N hand edits: hand-editing has a per-site error probability that compounds over the tail — the 180th edit gets less attention than the 5th (allocation, not motivation — core.md). A codemod has ONE error surface, reviewed once, applied uniformly — and is re-runnable: after a rebase, after the re-scan finds stragglers, in the sibling repo.
• The codemod is a migration artifact: save it alongside the report (Plans location) and cite it in the output. It touches mechanical sites only — judgment sites stay out of its reach.
• The tool changes nothing else about the discipline: inventory first, pilot proves it, batches still verify with targeted tests, the re-scan must still come back empty.

Phase 4 — Batched execution

Work the inventory in fixed batches (~10–20 mechanical sites, grouped by module so targeted tests cover each batch):

1. Transform the batch (matching each file's local idiom, not just the recipe literal).
2. Run test:targeted for the touched modules — green before the next batch.
3. Tick the batch's rows in the inventory file — done, or deferred / judgment with the reason — before starting the next batch. A row still reading todo is an untouched site, whatever the chat remembers.
4. Judgment sites: batch them separately — for each, show the site + your proposed change + the semantic difference, and apply only what the user confirms.
5. After each batch, output the suggested git add <paths> && git commit command (the user commits; batch-sized commits keep the migration bisectable). Never run it.

If the same class of failure appears in two batches — stop, fix the recipe, and re-check the already-done batches for the same defect (the two-strikes rule at migration scale).

Phase 5 — Zero-leftover verification

The sweep is done when re-discovery returns empty, not when the checklist does:

1. Re-run the full Phase 2 discovery (all angles). Every hit is: transformed ✓, deferred (with reason + owner), or a named intentional exception. Anything else → back to Phase 4.
2. Run the full test suite + lint (PROJECT.md → Commands).
3. If the old symbol/library should now be gone entirely: assert its absence (grep clean; dependency removed from the manifest — suggest the removal command).

Output

## Sweep — <transform>

### Coverage
- Sites found: N (angles: symbol / strings / dynamic / files)
- Transformed: X · Judgment-confirmed: Y · Deferred: Z (each with reason) · Exceptions: W
- Re-scan: CLEAN | <remaining hits>

### Verification
<targeted per batch: green> · <full suite: result> · <old-symbol absence: clean/n-a>

### Suggested commits
<the per-batch git commands, or "already output per batch">

### Deferred / follow-ups
- `path:line` — <why deferred> → <route: /prepare | owner>

Persist to the artifact

(Mandatory when $ARGUMENTS or the session brief names a plan, card or spec file.) Follow ../implement/reference/work-log.md. Keep a ledger on disk from the first phase and record deviations the moment they are decided. Before the final reply, append ## Sweep Log — <date> — <verdict> to that file; its ### Result is the Coverage block above, plus the paths of the site-inventory file and of the codemod, if one was written. Anything you could not observe yourself goes under Re-check later, with its command and today's baseline: a post-deploy log grep, a soak count, a UI gesture. The chat output is a copy of the log, never the only record. No planning artifact → skip this section.

Hard rules

• Inventory before any edit. No transform until the site table exists in a file with a total count — and every batch updates it in place before the next one starts.
• No silent truncation. Every bound on coverage is stated; every inventory row ends as transformed / deferred-with-reason / named exception.
• Pilot before scale. An unconfirmed recipe never touches the long tail.
• ~30+ mechanical sites → codemod. Hand-editing a long tail is a compounding error surface; write the tool, prove it on the pilot, keep it as the artifact.
• Judgment sites are proposed, never auto-applied. Semantic changes get user confirmation.
• Done = re-scan clean. The finish line is empty re-discovery + green full suite, not an inventory with every row ticked.
• Never commit. Output batch-sized commit commands; the user runs them.
• Facts from PROJECT.md. Commands and scope boundaries come from the profile.

Cross-reference

• /clean-mvp — removal of dead things (this skill changes live things).
• /refactor — one-diff cleanups; /prepare → /implement — when the "migration" turns out to need design (a judgment-site majority is that signal).
• /discover — the multi-modal search discipline Phase 2 reuses.
• /retro — after a large sweep, feed what the inventory missed on the first pass back into the kit.