> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blocks.team/llms.txt
> Use this file to discover all available pages before exploring further.

# Plan Mode

## Overview

Plan Mode allows you to work with Blocks to create a detailed implementation plan before any code changes are made. This collaborative planning phase helps ensure alignment on the approach before execution begins.

## How Plan Mode Works

### Starting a Session in Plan Mode

When creating a new session, you can choose to start in Plan Mode. This is available across all Blocks integrations:

* **Dashboard**: Select "Plan Mode" when starting a new session
* **Slack**: Use `@blocks /plan <your request>` to start a new session in Plan Mode
* **GitHub**: Use `@blocks /plan <your request>` in an issue, PR, or review comment
* **Linear**: Use `@blocks /plan <your request>` in an issue comment

**Example:**

```
@blocks /plan implement user authentication with OAuth
```

<Note>
  Plan Mode must be started with a **new session**. You cannot enter Plan Mode in a thread or conversation that has already begun.
</Note>

### The Planning Process

Once in Plan Mode:

1. **Describe Your Goal**: Tell Blocks what you want to accomplish
2. **Collaborative Planning**: Blocks will create an initial implementation plan
3. **Refine the Plan**: Work with Blocks to update and improve the plan
   * Ask questions about the approach
   * Request changes to specific steps
   * Add or remove requirements
4. **Review**: Once satisfied, review the complete plan displayed as `PLAN.md` in your session

### Implementing the Plan

When you're ready to proceed:

* Click the **"Implement this plan"** button in the session
* Blocks will switch to Edit Mode and execute the planned changes
* All context from the planning phase is preserved

## Important Limitations

<Warning>
  **One-Way Transition**: Once a session enters Edit Mode (either by implementing a plan or starting directly in Edit Mode), you cannot return to Plan Mode in that session. Plan Mode is only available at the start of a new session.
</Warning>

This design ensures a clear workflow:

* **Plan Mode** → Collaborative planning and refinement
* **Edit Mode** → Implementation and code changes

If you need to create a new plan after implementation has started, begin a new session.

## When to Use Plan Mode

Plan Mode is ideal for:

* **Complex Features**: Multi-step implementations that benefit from upfront planning
* **Architectural Decisions**: When you want to discuss and align on the approach before coding
* **Learning**: Understanding how Blocks would approach a problem before changes are made
* **Collaboration**: Working with Blocks to refine requirements and implementation strategy

## When to Skip Plan Mode

You can start directly in Edit Mode for:

* **Simple Changes**: Quick fixes or straightforward modifications
* **Clear Requirements**: When the implementation approach is obvious
* **Iterative Work**: Continuing work from a previous session
* **Urgent Fixes**: When you need immediate changes

## Best Practices

* **Be Specific**: Provide clear goals and requirements during planning
* **Ask Questions**: Use Plan Mode to explore different approaches
* **Review Thoroughly**: Make sure you're satisfied with the plan before implementing
* **Iterate**: Don't hesitate to request changes to the plan multiple times
* **Start Fresh**: Begin a new session if you need to plan additional work after implementation

***

Plan Mode gives you control over the development process, ensuring you and Blocks are aligned on the approach before making any changes to your codebase.