plan-mode

Files (1)

• SKILL.md

SKILL.md (first lines)

# Plan Mode

When triggered, switch into **planning mode**: analyze the task, produce a structured plan, and wait for explicit user approval before writing any code or making changes.

The core philosophy: **think deeply, communicate clearly, execute only when aligned.**

## When to Enter Plan Mode

- User explicitly requests it (`/plan`, "plan this", "think first", etc.)
- Task touches 3+ files or components
- Task involves architecture decisions, new patterns, or breaking changes
- Task is ambiguous and could be approached multiple ways
- Task involves infrastructure, CI/CD, database changes, or migrations
- You're unsure about the right approach

## Plan Output Structure

Produce a plan with these sections. Adapt depth to task complexity — a small bug fix needs a lighter plan than a new feature.

### 1. Understanding (What)

Restate the task in your own words to confirm understanding. Call out any ambiguities or assumptions you're making. This catches misalignment early.

```
## Understanding
[Restate the goal in 2-3 sentences]

**Assumptions:**
- [List anything you're assuming that wasn't explicitly stated]

**Open questions:**
- [List anything you need clarified before proceeding]
```

If there are open questions that would significantly change the approach, STOP here and ask the user before continuing with the plan. Don't build a full plan on shaky assumptions.

### 2. Approach Options (How)

For non-trivial tasks, present 2-3 distinct approaches. For simple tasks, present one recommended approach with brief justification.

For each option include:
- **Summary**: One-line description
- **How it works**: Key implementation steps (keep high-level, not line-by-line)
- **Pros**: Why this approach is good
- **Cons**: Tradeoffs and risks
- **Effort estimate**: Relative complexity (small / medium / large)

End with a clear recommendation and why.

```
## Approach Options

### Option A: [Name]
**Summary:** [One line]
**How it works:** [3-5 bullet points, high-level]
**Pros:** [What's good about this]
**Cons:** [Tradeoffs]
**Effort:** [small / medium / large]

### Option B: [Name]
...

**Recommendation:** Option [X] because [reason tied to project context].
```

### 3. Task Breakdown (Steps)

Break the chosen (or recommended) approach into concrete, ordered steps. Each step should be small enough to verify independently. Group related steps into phases.

```
## Task Breakdown

### Phase 1: [Name, e.g. "Setup / Preparation"]
- [ ] Step 1.1: [Concrete action]
- [ ] Step 1.2: [Concrete action]
  **Checkpoint:** [What should be true after this phase — a testable condition]

### Phase 2: [Name, e.g. "Core Implementation"]
- [ ] Step 2.1: [Concrete action]
- [ ] Step 2.2: [Concrete action]
  **Checkpoint:** [Testable condition]

### Phase 3: [Name, e.g. "Verification & Cleanup"]
- [ ] Step 3.1: [Concrete action]
- [ ] Step 3.2: [Concrete action]
  **Checkpoint:** [Testable condition]
```

Guidelines for good steps:
- Each step modifies 1-2 files at most
- Steps are ordered so the project stays in a working state after each phase
- Include test/verification steps, not just implementation
- Checkpoints are concrete and testable ("tests pass", "server starts", "endpoint returns 200")

### 4. Risk Assessment

Identify what could go wrong and how to mitigate it. Focus on risks specific to *this* task, not generic software risks.

```
## Risks

| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|
| [Specific thing that could go wrong] | low/med/high | low/med/high | [How to prevent or handle it] |
```

Always consider:
- **Breaking changes**: Will this break existing functionality? Which consumers/callers are affected?
- **Data implications**: Any database migrations, data loss risk, or state changes?
- **Rollback**: If this goes wrong, how hard is it to undo?
- **Dependencies**: External services, libraries, or team coordination needed?

### 5. Files & Scope

List the files that will be created, modified, or deleted. This helps the user understand the blast radius.

```
## Affected Files
- **Create:** `path/to/new-file.ts` — [purpose]

From espennilsen/pi, MIT.

More from espennilsen/pi