Refactors & migrations

Sweeping changes — renames, API migrations, dependency swaps — are where find-and-replace anxiety lives. This guide shows Mel's shape for them: scope first, plan on screen, apply in small verified edits, and read the whole result in the review panel before it lands.

1. Isolate the work (optional but recommended)

For a migration you don't want on your working branch, start it in a git worktree: track your repo once (+ tab menu → "Track this repo"), then + → Worktree: your-repo creates a fresh checkout under ~/.mel/worktrees on a generated branch and opens a tab in it. Your main checkout stays untouched until you merge. See Tab configs & the + menu.

2. Scope it with a plan

Start a conversation (ctrl+enter) and ask for a plan before any code — or use the /plan slash command. With the agent's write_plan tool, the plan opens as a document in a side panel next to the conversation:

Before writing any code: explore the codebase, then produce a plan document
for the change I described — goals, files to touch, step order, risks, and
how we'll verify each step. Put it in a plan I can read side-by-side, and
wait for my sign-off before implementing.

The agent enumerates affected files with grep and find_files first, so the plan is grounded in actual call sites, not guesses.

3. Choose your approval posture

Edits are surgical: the agent reads a file before editing it, and each edit is an exact, unique-match replacement — it can't smear a change across the wrong lines. You control how much you gate:

• Default: every write and command round-trips an approval card — Allow, Always allow (per kind, for this conversation), or Deny. Good for the first few edits while you calibrate trust.
• Autonomous (A⁺): toggle the A⁺ chip in the input footer and the run goes hands-off — the agent edits, builds, and fixes without stopping. Best once the plan is approved and the change is mechanical. See Autonomous mode.

For very large builds, a lead agent can split the work across worker agents in their own panes — see Orchestration.

4. Read the diff cards as they land

Every applied change produces a diff card in the transcript: the path, +A −D counts, and red/green line rows. The end-of-turn usage summary reports real files-changed and diffs-applied numbers, so you always know the blast radius. The agent verifies as it goes — re-reading edited files and running your build or tests — and fixes what breaks rather than leaving the tree red.

5. Final pass in the code review panel

When the sweep is done, open the code review panel (ctrl+shift+=). All the migration's uncommitted changes load as per-file diff cards with an index, per-file +/− counts, and syntax highlighting — the right altitude for a final read. From there:

• Drop inline comments on anything off and Send to Agent for a follow-up round.
• ↩ Discard any file the migration shouldn't have touched.
• Then hand the commit-and-PR step back to the agent — see Do things with Mel.