Plan mode conflates 'format my document nicely' with 'execute the plan'

Plan mode conflates "format my document nicely" with "execute the plan"

TL;DR

Plan mode is the only place in Claude Code where a markdown document renders as readable formatted text in the IDE. But the only way out of plan mode is "approve" (which means execute the plan) or "reject." There is no "I just wanted to read this nicely formatted" exit. Review-style deliverables — code reviews, audits, design critiques, principal-engineer write-ups — have nothing to "execute." The user is forced to choose between accepting an action they don't want or rejecting and losing the rendered view.

Concrete scenario

I asked Claude to do a /srmanager-review on a plan file. The natural shape of that work is:

1. Claude verifies claims, queries APIs, reads code.
2. Claude writes a multi-section review document with findings, severity, fixes.
3. I read the review and decide what (if anything) to do next.

The review is itself the deliverable. There is nothing to "implement" — it's analysis, not a TODO list.

What actually happened:

• Claude (correctly) entered plan mode because /srmanager-review is configured that way.
• Claude wrote the review to /Users/me/.claude/plans/srmanager-review-users-...-soft-tarjan.md — a path I would never find on my own. Auto-generated filename, buried directory.
• Claude tried to call ExitPlanMode. I rejected it because the button reads "approve plan" which sounds like consent to execute.
• I asked Claude to send me the plan in "easy to read format, not markdown." Claude pasted plain text in chat, which was fine but cluttered the conversation.
• I pointed out that what I actually wanted was the rendered "Ready for review" panel from plan mode.
• Claude called ExitPlanMode. The panel rendered correctly. I clicked approve to dismiss the panel — which Claude reasonably interpreted as "go implement the review's recommendations." I had to interrupt to clarify I just wanted to see it formatted.

What's actually wrong

1. "Approve plan" is overloaded

The ExitPlanMode panel's primary CTA executes the plan. For review-only deliverables, the user wants to read it, not execute it. There's no third button — something like "Got it, just close this." The user has to either lie (approve, then immediately tell Claude to do nothing) or reject (which makes Claude think they want to start over).

Suggested fix: Add a "Close (no action)" button to ExitPlanMode panels. Or detect that a plan has no actionable steps (it's a review, audit, analysis) and present a different CTA.

2. Plan files land in an unfindable directory with auto-generated names

~/.claude/plans/srmanager-review-users-pipermiles-cocca-soft-tarjan.md — the suffix is random, the directory isn't surfaced anywhere in the UI. If I want to come back to this review tomorrow, I have to remember the directory exists, then guess which auto-generated filename was mine.

Suggested fix: Either let the user choose a path/name when entering plan mode, or surface a "recent plans" list in the IDE sidebar. At minimum, generate filenames from the actual content (first H1, first task verb), not from the slash-command name + tail of working dir.

3. There's no other way to render a markdown deliverable in the IDE

Clicking a .md file link in chat opens the source view. Markdown preview exists in VS Code but is two clicks away and not the default. The plan-mode panel is currently the only "first-class" rendered markdown in Claude Code's chat UI.

Suggested fix: Add a "render markdown" affordance to file links in chat for .md files. Or, more ambitious: when Claude produces a long-form markdown document (review, audit, design doc), render it in-line in chat with a "save to file" button — totally decoupled from plan mode.

4. Plan mode's mental model assumes "plan → execute" but skills like /srmanager-review produce read-only output

The slash command /srmanager-review and similar review/audit commands have no action phase. They produce a document. Plan mode is the wrong abstraction for these — but it's the abstraction these commands currently use because plan mode is also the only way to get nice rendering.

Suggested fix: Distinguish between "plan mode for actionable plans" and "review mode for read-only deliverables." Both can use the same nice rendering panel; only the former should have an "approve & execute" CTA.

Why this matters

The user (me) figured this out only by trial and error. Claude (a capable agent) was confused enough by the UI to get the format wrong twice in a row before landing on "call ExitPlanMode for the rendering." That's a meaningful signal: if the model is guessing at the right interaction pattern, the UI is asking the user to do work the model can't do for them.

The bigger issue: it makes Claude Code feel like it's optimized for "agents writing code" and not for "humans reading what agents produced." For someone using Claude as a thinking partner — code reviews, design critiques, second opinions — the read-back path is just as important as the execute path, and right now it's a worse experience.

What I'd want, in priority order

1. A way to dismiss a plan-mode panel without "approving" it (third button, or rename "approve" to something less action-coupled when no action is configured).
2. Render markdown deliverables in chat without plan mode at all — file-link previews or inline rendering.
3. Better plan-file naming and discoverability.

Thanks for reading. Happy to elaborate or test fixes.