Your first plan-mode session

What plan mode is — and isn’t

Plan mode is a Claude Code switch that puts the agent into “design before action.” Instead of executing tools immediately, the agent reads context, drafts a structured plan, and waits for your approval. You read the plan, push back on what’s wrong, and approve when it’s right. Then the agent executes that plan exactly.

The value is not that the agent thinks harder. The value is that you get to see what it’s about to do before it does it. Plan mode trades 30-90 seconds of planning for the ability to catch a wrong file path, a missed input, or an over-broad scope before any side effects happen.

Plan mode is not:

• A substitute for thinking. If you don’t know what you want, the plan won’t either.
• A magic correctness layer. The agent can plan a wrong thing perfectly.
• Free. It costs tokens and elapsed time. Only earns its place when the task is plan-shaped.

The skill in this lesson is two things: recognizing when a task is plan-shaped, and reading the resulting plan with discipline. Most operators get the first part right and the second part wrong — they approve plans they barely read, then act surprised when the agent did exactly what the plan said.

When to drop into Plan

The decision rule is two questions:

1. File fan-out. Does this task touch 3+ files or modules? If yes, plan mode. The cost of a wrong file list is high.
2. Irreversibility. Does any step have side effects you can’t cheaply undo? Deploys, schema migrations, deletions, sent emails, money-moving operations, signed documents. If yes, plan mode regardless of file count.

Either yes triggers plan mode. Two yeses make plan mode mandatory.

Examples from the TruPath portfolio:

• Plan mode: “Compare Hickory and Denver sites for the SBA loan repoint memo” — multi-file, decision-shaping. The transcript below.
• Plan mode: “Update the QC patent provisional draft to swap FSR claims for radar/ToF method claims” — irreversible (filing) + multi-file (claim language, evidence ledger, abstract).
• Plan mode: “Migrate the Supabase trupath_tasks schema to add a venture_id constraint” — schema migration, irreversible without a careful rollback.
• Just edit: “Add a one-line note to CLAUDE.md.” Single file, reversible. Plan mode is overhead.
• Just edit: “Fix the typo in the homepage hero.” Single line, instantly reversible.

Most operators err in one direction: they enter plan mode for trivial work because they’ve been burned, or skip it on serious work because they’re in a hurry. The decision rule above resolves both.

Three plan-mode failure modes

Each one wastes time without producing the safety plan-mode is supposed to deliver. Hover any card.

The pattern across all three: plan mode is a contract between operator and agent. Misuse the mode and you get the cost without the protection.

The “is this plan-shaped?” test

The 30-second screen before you flip the switch:

Before I drop into plan mode, ask:

1. Does this task span 3+ files OR touch an irreversible operation
   (deploy, migration, deletion, send-email, financial-commit)?
   - Yes → plan mode earns its place
   - No → just edit

2. Is my intent clear enough that I could write a 5-bullet plan
   myself in 60 seconds?
   - Yes → plan mode helps catch missed file/order issues
   - No → 5-min conversation to clarify intent FIRST, then plan

3. Am I about to use plan mode because I'm uncertain what I want?
   - Yes → STOP. Plan mode won't fix unclear intent. Talk it out first.

If 1=yes and 2=yes, run plan mode. Read every line. Approve only
after you've checked: file list, order of ops, won't-do clauses.

When the answer is “back to conversation,” that’s the most valuable outcome. It catches the moment when an operator is using plan mode to substitute for unclear intent — which never works.

Annotated transcript — MHG site comparison memo

A real plan-mode session for the Hickory→Denver site pivot memo. Watch the structure of the plan and the way the operator pushes back twice before approving.

Prompt kit

Three prompts: the screening test, a plan-structure enforcer, and a guard against runaway revisions.

Before I drop into plan mode, ask:

1. Does this task span 3+ files OR touch an irreversible operation
   (deploy, migration, deletion, send-email, financial-commit)?
   - Yes → plan mode earns its place
   - No → just edit

2. Is my intent clear enough that I could write a 5-bullet plan
   myself in 60 seconds?
   - Yes → plan mode helps catch missed file/order issues
   - No → 5-min conversation to clarify intent FIRST, then plan

3. Am I about to use plan mode because I'm uncertain what I want?
   - Yes → STOP. Plan mode won't fix unclear intent. Talk it out first.

If 1=yes and 2=yes, run plan mode. Read every line. Approve only
after you've checked: file list, order of ops, won't-do clauses.

Reissue your plan with this exact structure:

## Inputs
- <files / sources you'll read>

## Work
- <axes, steps, or transformations — numbered>

## Output
- <exact file path>
- <scope: word count, fields, schema, etc.>

## Won't do
- <explicit anti-actions — what this plan will NOT touch>

Don't continue until that structure is filled in. Approve only
the structured plan.

If we're on plan revision 3 or later, stop revising the plan.
Tell me what about my original ask is unclear or contradictory.
We'll resolve that in conversation, then re-enter plan mode with
a clearer brief.

Apply this — your first deliberate plan-mode session

30-minute exercise. Pick a real task. Run plan mode end-to-end. Verify the won’t-dos held.