review-plan

What this skill does

# Review Plan Skill

Edit and update all existing plan files based on user feedback, following the same orchestration flow as `/plan`.

---

## How It Differs from /plan

| Aspect | /plan | /review-plan |
|--------|-------|-------------|
| Purpose | Create plans from scratch | Edit existing plans |
| Input | PRD file | User feedback + existing plans |
| Agent action | Write new files | Read existing files, apply changes, rewrite |
| progress.json | Not created (use /complete-plan) | Updated/regenerated if it exists |
| Prerequisite | PRD must exist | Plan files must exist |

---

## Flow

```
/review-plan [user feedback OR empty]
      |
      v
+----------------------------------------------------------+
|  STEP 1: Get review feedback                              |
|  - From arguments: /review-plan change auth to OAuth      |
|  - OR from AskUserQuestion if no arguments provided       |
+----------------------------------------------------------+
      |
      v
+----------------------------------------------------------+
|  STEP 2: Verify existing plan files                       |
|  - docs/ui-ux-plan.md (REQUIRED)                         |
|  - docs/dev-plan.md (REQUIRED)                            |
|  - docs/frontend-plan.md (REQUIRED)                      |
|  - docs/backend-plan.md (REQUIRED)                        |
|  - docs/progress.json (optional — update if exists)       |
+----------------------------------------------------------+
      |
      v
+----------------------------------------------------------+
|  STEP 3: ui-ux-specialist (SEQUENTIAL)                   |
|  - Reads: docs/ui-ux-plan.md + user feedback              |
|  - EDITS and rewrites: docs/ui-ux-plan.md                |
+----------------------------------------------------------+
      |
      v
+----------------------------------------------------------+
|  STEP 4: tech-lead-specialist (SEQUENTIAL)               |
|  - Reads: updated docs/ui-ux-plan.md + user feedback      |
|  - EDITS and rewrites: docs/dev-plan.md                  |
+----------------------------------------------------------+
      |
      v
+----------------------------------------------------------+
|  STEP 5: PARALLEL — frontend + backend specialists       |
|                                                           |
|  frontend-specialist                                      |
|  - Reads: updated docs/dev-plan.md + user feedback        |
|  - EDITS and rewrites: docs/frontend-plan.md             |
|                                                           |
|  backend-specialist                                       |
|  - Reads: updated docs/dev-plan.md + user feedback        |
|  - EDITS and rewrites: docs/backend-plan.md              |
+----------------------------------------------------------+
      |
      v
+----------------------------------------------------------+
|  STEP 6: progress-creator (SEQUENTIAL, only if exists)   |
|  - Reads: updated dev-plan.md, frontend-plan.md,          |
|           backend-plan.md                                 |
|  - Rewrites: docs/progress.json                          |
+----------------------------------------------------------+
      |
      v
+----------------------------------------------------------+
|  STEP 7: Report changes                                   |
+----------------------------------------------------------+
```

---

## Step 1: Get Review Feedback

### Option A: Feedback from arguments

If the user invokes with arguments:
```
/review-plan change the auth flow to use OAuth instead of magic links
/review-plan add a dark mode toggle to the settings page
/review-plan remove the billing feature entirely
```

Extract the feedback directly from the arguments. **Do NOT ask questions — the user already told you what to change.** Proceed directly to Step 2.

### Option B: No arguments provided

If the user invokes with no arguments (`/review-plan`), you MUST use AskUserQuestion to gather feedback.

```
AskUserQuestion:
  question: "What changes would you like to make to the plan?"
  header: "Change Type"
  options:
    - label: "Add a feature"
      description: "Add a new feature or capability to the plan"
    - label: "Remove a feature"
      description: "Remove an existing feature from the plan"
    - label: "Change approach"
      description: "Modify how a feature is implemented"
    - label: "I'll describe it"
      description: "Provide detailed feedback in my own words"
```

Then follow up with a specific question based on their choice:

**If "Add a feature":**
```
AskUserQuestion:
  question: "What feature would you like to add? Describe it briefly."
  header: "New Feature"
  options:
    - label: "New page/screen"
      description: "Add a new page with its own route"
    - label: "New component/widget"
      description: "Add a new UI element to an existing page"
    - label: "New backend capability"
      description: "Add new tables, APIs, or data processing"
    - label: "I'll describe it"
      description: "Let me explain what I need"
```

**If "Remove a feature":**
```
AskUserQuestion:
  question: "Which feature should be removed?"
  header: "Remove"
  options:
    - label: "I'll specify it"
      description: "Let me name the feature to remove"
```

**If "Change approach":**
```
AskUserQuestion:
  question: "What would you like to change?"
  header: "Change"
  options:
    - label: "UI/UX design"
      description: "Change layout, colors, components, user flows"
    - label: "Backend/database"
      description: "Change schema, APIs, data model"
    - label: "Tech stack"
      description: "Change frameworks, libraries, tools"
    - label: "I'll describe it"
      description: "Let me explain the change"
```

### Question Rules
- Maximum **3 questions** to gather feedback
- If the user provided arguments, ask **ZERO questions** — use their input directly
- Capture the full feedback as `{user_feedback}` for all agent prompts

---

## Step 2: Verify Existing Plan Files

Check that required plan files exist:

```
Glob: **/ui-ux-plan.md
Glob: **/dev-plan.md
Glob: **/frontend-plan.md
Glob: **/backend-plan.md
Glob: **/progress.json
```

### If any REQUIRED file is missing:

Tell the user which files are missing and suggest running `/plan` first:

> Missing: `[file]`. Run `/plan` first to create all plan files, then use `/review-plan` to edit them.

**STOP. Do NOT proceed with partial plans.**

### Track progress.json existence:

```
has_progress_json = true/false
```

If `progress.json` exists, it will be regenerated in Step 6.

---

## Step 3: Spawn ui-ux-specialist — EDIT Mode (SEQUENTIAL)

```
Task:
  subagent_type: ui-ux-specialist
  description: "Edit UI/UX plan"
  prompt: |
    You are in REVIEW/EDIT mode — NOT creating from scratch.

    Read the EXISTING plan:
    - docs/ui-ux-plan.md

    User feedback to apply:
    ---
    {user_feedback}
    ---

    Instructions:
    1. Read docs/ui-ux-plan.md completely
    2. Identify which sections are affected by the user's feedback
    3. Apply the requested changes to those sections
    4. Keep all UNAFFECTED sections exactly as they are — do not rewrite unchanged content
    5. Add a "## Revision Log" section at the bottom with:
       - Date of revision
       - Summary of what changed
    6. Write the updated file back to: docs/ui-ux-plan.md

    IMPORTANT:
    - This is an EDIT, not a rewrite. Preserve existing work.
    - Only change what the user asked to change.
    - If the feedback doesn't affect UI/UX (e.g., only backend changes), make no changes and return "No UI/UX changes needed."

    Write the file using the Write tool. Return "Done: docs/ui-ux-plan.md [summary of changes]" when complete.
```

**Wait for completion before proceeding.**

Verify:
```
Glob: docs/ui-ux-plan.md
```

---

## Step 4: Spawn tech-lead-specialist — EDIT Mode (SEQUENTIAL)

```
Task:
  subagent_type: tech-lead-specialist
  description: "Edit dev plan"
  prompt: |
    You are in REVIEW/