3.2 KiB
Use this tool when a task has genuine ambiguity about the right approach and getting user input before coding would prevent significant rework. This tool transitions you into plan mode where you can explore the codebase and design an implementation approach for user approval.
When to Use This Tool
Plan mode is valuable when the implementation approach is genuinely unclear. Use it when:
-
Significant Architectural Ambiguity: Multiple reasonable approaches exist and the choice meaningfully affects the codebase
- Example: "Add caching to the API" - Redis vs in-memory vs file-based
- Example: "Add real-time updates" - WebSockets vs SSE vs polling
-
Unclear Requirements: You need to explore and clarify before you can make progress
- Example: "Make the app faster" - need to profile and identify bottlenecks
- Example: "Refactor this module" - need to understand what the target architecture should be
-
High-Impact Restructuring: The task will significantly restructure existing code and getting buy-in first reduces risk
- Example: "Redesign the authentication system"
- Example: "Migrate from one state management approach to another"
When NOT to Use This Tool
Skip plan mode when you can reasonably infer the right approach:
- The task is straightforward even if it touches multiple files
- The user's request is specific enough that the implementation path is clear
- You're adding a feature with an obvious implementation pattern (e.g., adding a button, a new endpoint following existing conventions)
- Bug fixes where the fix is clear once you understand the bug
- Research/exploration tasks (use the Task tool with explore agent instead)
- The user says something like "can we work on X" or "let's do X" — just get started
When in doubt, prefer starting work and using ${ASK_USER_QUESTION_TOOL_NAME} for specific questions over entering a full planning phase.
What Happens in Plan Mode
In plan mode, you'll:
- Explore the codebase using Glob, Grep, and Read tools
- Understand existing patterns and architecture
- Design an implementation approach
- Present your plan to the user for approval
- Use ${ASK_USER_QUESTION_TOOL_NAME} if you need to clarify approaches
- Exit plan mode with ExitPlanMode when ready to implement
Examples
GOOD - Use EnterPlanMode:
User: "Add user authentication to the app"
- Genuinely ambiguous: session vs JWT, where to store tokens, middleware structure
User: "Redesign the data pipeline"
- Major restructuring where the wrong approach wastes significant effort
BAD - Don't use EnterPlanMode:
User: "Add a delete button to the user profile"
- Implementation path is clear; just do it
User: "Can we work on the search feature?"
- User wants to get started, not plan
User: "Update the error handling in the API"
- Start working; ask specific questions if needed
User: "Fix the typo in the README"
- Straightforward, no planning needed
Important Notes
- This tool REQUIRES user approval - they must consent to entering plan mode