Refactor a class with Plan mode

Plan mode is for multi-file refactors where you want to align on the approach before any code changes. This tutorial walks through one — a small but realistic refactor — and shows where Plan mode shines and where it can go wrong.

Time required: about 20 minutes. You need a project with at least one class that's grown big enough that you've thought about splitting it.

Pick a target

Find a class in your project that's 300+ lines, does at least two distinct things, and has some test coverage you trust. We'll extract one responsibility into a new class while keeping the old one's tests green.

For this tutorial we'll call it UserService. Substitute your own. The responsibility we'll extract is email validation.

Step 1 — Switch to Plan mode

Above the chat input, switch the mode selector from Ask / Agent to Plan. Plan is read-only during the planning step — Scout will read files but not write.

Step 2 — Brief Plan

Attach your target file with #file. Then:

Refactor `UserService` to extract email validation into a new
`EmailValidator` class. Keep the existing tests green. Add a
regression test for the new validator.

Send. Plan will issue several read calls in one go (the prompt explicitly tells it to — sequential reads waste round-trips). You'll see it pull in the user service, the existing tests, and possibly other call sites of the email logic.

Step 3 — Read the plan

Plan emits a structured checklist. Each phase has:

A title (e.g. Extract email validation)
A summary of what the phase does
The deliverable (which files change)
Step-by-step actions inside the phase
Acceptance criteria (how you know the phase is done)
A Run Phase button

Read every phase before running anything. This is the moment Plan mode pays off — you can disagree with the structure, edit phases, reorder them, or scrap the plan entirely without having paid any token cost for execution.

Step 4 — Run phase 1

Click Run Phase 1. Pearl re-sends the phase as an Agent-mode request, scoped to that phase. The Agent gets full tools (read, write, edit, run) but the prompt is narrower than "do the whole refactor" — it's "do this one phase."

Watch the editor. Hunks appear. Walk through them, accept what you want. The phase is done when:

You've accepted (or rejected) every hunk it proposed
The acceptance criteria pass

Step 5 — Run phase 2 (the test)

Now Run Phase 2 — adding the regression test. Same flow. The test should run green; if it doesn't, that's a real signal something in phase 1 isn't right. Don't paper over a failing test with retries.

Step 6 — Run phase 3 (verification)

Phase 3 is usually "build + lint + tests" — Agent runs them via the integrated terminal, reports any failures. If everything's green, you're done.

If something's red, the Agent will surface the failure. Don't loop. Stop, read the failure yourself, decide whether to fix it manually or ask Agent to fix it with the failure pasted in. Tight feedback loops > infinite retries.

Where Plan mode goes wrong

The plan is too aggressive. Plan likes to bundle "while we're here" changes into a phase. Read carefully and rip out anything that wasn't in your brief.
Phases skip a missing piece. Sometimes Plan assumes a helper exists that doesn't. Edit the phase to add the creation step.
Acceptance criteria are vague. If they are, the phase's "done" gate is weak. Tighten them before running.

What you just learned

Plan before Agent for anything multi-file.
The plan is editable — you don't owe it your trust.
Phase-scoped Agent runs beat one giant Agent run.
Build → Lint → Tests as the last phase is non-negotiable.

Now that you've done one real refactor, the memory tutorial will show you how to capture project conventions so Plan mode doesn't have to re-discover them every time.

Tutorial unclear or out of date? File feedback — we update these as Pearl ships.