---
name: rpi-plan
description: "Use after /rpi-research when you want an interactive, gated plan-creation flow. Interactive: presents understanding, design options, phase outline, then draft — each gated on user approval."
---

Create an implementation plan through an interactive, gated flow. Consumes `research.md` from `/rpi-research` 

**RPI principle:** Research documents what **is**. Plan decides what **should change**. Implement performs the **change** and verifies it.

**Announce at start:** "Starting /rpi-plan."

## Core Principle: Gated, Not Single-Shot

Plans built in one shot tend to bake in assumptions. This skill enforces **four explicit gates** so you can correct course before the plan crystallizes:

1. **Understanding gate** — present what's understood; resolve open questions
2. **Design option gate** — present 2-4 options grounded in research; pick one
3. **Phase outline gate** — confirm phase boundaries before writing details
4. **Draft review gate** — iterate on the written plan until satisfied

Each gate uses `AskUserQuestion`.

## Setup

1. Run `"$SKILL_BASE_DIR/setup.sh" "<slug>"` (extract `<slug>` from `$ARGUMENTS`). Parse stdout for `REPO`, `TOPIC_SLUG`, `ARTIFACT_DIR`. `$SKILL_BASE_DIR` is the "Base directory for this skill" path shown at the top of this prompt.
   - If exit 2, `AskUserQuestion` for slug.

## Pre-flight Validation

- If `<ARTIFACT_DIR>/plan.md` exists, `AskUserQuestion`: **Overwrite** / **New slug** / **Abort**.
- Check `<ARTIFACT_DIR>/research.md` — if missing, **Abort** and tell the user to run `/rpi-research` first.
- Check `<ARTIFACT_DIR>/research.md` — note presence; it determines Step 1's branch below.

## Process

### Step 1: Load context
1. Read `<ARTIFACT_DIR>/research.md` fully.
2. Read every file referenced under `## Code References` whose contents will materially shape the plan. Use the `Read` tool with no offset/limit on the most relevant 3-5 files; skim the rest.

### Step 2: Gate 1 — Understanding

Present a focused summary:

```
Based on <research.md | inline research>, here's what I understand:

- <current implementation detail with file:line>
- <key pattern or constraint discovered>
- <potential complexity / edge case>

Open questions I couldn't resolve from the code:
- <question 1>
- <question 2>
```

Ask the user each open question (batch when ≤4 questions; otherwise prioritize the load-bearing ones). Only ask questions code can't answer — don't waste a gate on things you could verify with one more file read.

If the user corrects a stated understanding, **verify the correction by reading the relevant code** before accepting it. Do not just take dictation.

### Step 3: Gate 2 — Design Option Pick

Surface 2-4 plausible approaches, each citing research findings as evidence. Skip this gate only if there's genuinely one obvious approach (and say so explicitly).

For each option:

```
**Option A: <name>**
- Approach: <one sentence>
- Evidence: <file:line refs from research showing why this fits>
- Tradeoffs: <pros / cons>

**Option B: <name>**
...
```

Use `AskUserQuestion` with the options as choices. Capture the user's pick + rationale in a buffer — it will land in the plan's header.

### Step 4: Gate 3 — Phase Outline

Propose phase boundaries (1-line each). Each phase must be **independently testable** and produce a working unit.

```
Proposed phasing:

1. <Phase 1 name> — <what it produces; validation command>
2. <Phase 2 name> — <what it produces; validation command>
3. <Phase 3 name> — <what it produces; validation command>

Total: ~<N> tasks across <M> phases.
```

Use `AskUserQuestion`: **Confirm phasing** / **Adjust phase boundaries** / **Adjust task granularity** / **Abort**.

If the user requests adjustments, iterate until they confirm. Keep phase boundaries independently testable and adjust task granularity until the outline is clear enough to draft.

### Step 5: Gate 4 — Draft and Review

Read `./plan-template.md`, then write the plan to `<ARTIFACT_DIR>/plan.md` using that structure. Then announce:

```
Plan drafted at <path>.

Please review:
- Are tasks small enough for one fresh subagent to complete safely, with clear tests/validation?
- Are success criteria specific and runnable?
- Anything missing or out of scope to drop?
```

Iterate via Edit until the user signals satisfaction. **No open questions in the final plan** — if something is unresolved, return to Gate 2 or 3.

## Plan Template (dw-05 format)

Read `./plan-template.md` and use that exact structure for `<ARTIFACT_DIR>/plan.md`. The template includes required execution progress fields, task/phase format, and task granularity guidance.

## Completion

1. Confirm artifact path, phase count, task count.
2. Instruct: "Plan ready at `<ARTIFACT_DIR>/plan.md`. Review once more, then run `/rpi-implement <slug>` to execute."

## Red Flags

**Stop and reconsider if:**
- A gate gets skipped because "the user will catch it later" — gates exist because they're cheaper than fixing the plan after implementation starts.
- An option at Gate 2 has no evidence from research — that's a design hunch, not a grounded option. Either find the evidence or drop the option.
- The plan would contain placeholders or "TBD" — return to the appropriate gate; placeholders become bugs.
- The plan is becoming vague because the scope is large — tighten phase boundaries, task granularity, success criteria, and scope guards before drafting.

## Notes on the four-gate flow

Gates aren't ceremony — each one prevents a specific failure mode:

| Gate | Prevents |
|------|----------|
| Understanding | Planning around a misread of current state |
| Design option | Locking in an approach the user wouldn't have picked |
| Phase outline | Phases that aren't independently testable or are wrongly ordered |
| Draft review | Tasks too vague for `/rpi-implement` to dispatch cleanly |

If a gate feels redundant in a given session (e.g., the user gave the design decision upfront), state the assumption explicitly and ask once for confirmation rather than skipping silently.