Mechanism: Mode Switching
One-sentence definition
Mode switching is deliberately changing cognitive mode — plan, implement, debug, ask-only — so the agent (and you) do one kind of thinking per phase instead of designing and coding in the same undifferentiated chat.
The problem
You ask for a plan and the agent edits twelve files. Or you need root-cause analysis but the agent keeps patching symptoms. Mixing modes produces half-plans and half-diffs — neither reviewable as design nor shippable as code.
Modes are guardrails on what tools and outputs are appropriate.
Symptoms:
- Code changes before you approve approach
- Long debug stories with no edit — when you needed a fix
- Plan mode output still refactors production files
- “Just build it” without acceptance criteria
How it works
Plan ──► approve ──► Build (Agent)
│
└──► Debug (trace only, narrow)
│
└──► Ask (no edits, exploration)Plan — slices, AC, interfaces; stop when plan is approved.
Build — implement approved plan; stop on verify pass.
Debug — trace failure, minimal fix; stop when root cause is named.
Ask — learn codebase, no edits intended.
Escalation Level 3 is often a mode switch, not a model switch.
When to use it
- Non-trivial features — plan before agent edits
- Recurring wrong-layer fixes — switch to debug framing
- Interface-first — types in plan phase
- Reviewing teammate agent PR — ask mode for understanding first
When not to use it
- One-line typo — build mode only is fine
- Plan mode for tasks already fully specified with examples and tests
- Mode switching as procrastination — plan must end
Failure modes
Fake plan — Plan includes “I will now edit files.” Fix: No edits until explicit “go build.”
Stuck in plan — No implementation after approval. Fix: Goal + switch to build.
Debug that refactors — Debug mode wide refactors. Fix: Debug prompt: trace only, no edits until hypothesis confirmed.
Mode without checkpoint — Build starts before plan approval. Fix: Checkpoint on plan doc.
Minimal example
Context: Verbose health feature across slices.
Modes:
- Plan: List slices, AC, types — no
@implementation files for edit. - Approve: You reply “Build slice 1 only.”
- Build: Agent mode with slice 1 goal + constraints.
- Debug (if uptime 0): “Trace bootstrap order only; no refactor.”
Done when: Each phase produced one artifact type — plan doc, diff, or trace notes.
Tool instances (optional deep-dive)
Portable idea above; this section is tool-specific. Date: June 2026.
Cursor
- Plan mode vs Agent mode vs Ask mode — explicit UI switches.
- Start in Plan for multi-slice features; Agent only after approval message.
- Rules: “In plan mode, do not write to src/.”
Other tools
Separate chat roles, “architect” vs “implementer” prompts — same separation.
Related mechanisms
- Escalation — mode change as escalation step
- Interface-first — plan phase defines interfaces
- Checkpoint — gate between plan and build
Try it yourself
Exercise: Next non-trivial task — first message only in Plan (or ask-only). Second message approves and switches to build.
Done when: Zero implementation files changed before your approval message.