/plan

description: Restate requirements, assess risks, and create step-by-step implementation plan. WAIT for user CONFIRM before touching any code.
argument-hint: "[feature description | path/to/*.prd.md]"

Plan Command

This command creates a comprehensive implementation plan before writing any code. It accepts either free-form requirements or a PRD markdown file.

Run inline by default. Do not call the Task tool or any subagent by default. This keeps `/plan` usable from plugin installs that ship commands without agent files.

What This Command Does

1. **Restate Requirements** - Clarify what needs to be built 2. **Identify Risks** - Surface potential issues and blockers 3. **Create Step Plan** - Break down implementation into phases 4. **Wait for Confirmation** - MUST receive user approval before proceeding

When to Use

Use `/plan` when:

• Starting a new feature
• Making significant architectural changes
• Working on complex refactoring
• Multiple files/components will be affected
• Requirements are unclear or ambiguous

How It Works

The assistant will:

1. **Analyze the request** and restate requirements in clear terms 2. **Ground the plan** in relevant codebase patterns when the repo is available 3. **Break down into phases** with specific, actionable steps 4. **Identify dependencies** between components 5. **Assess risks** and potential blockers 6. **Estimate complexity** (High/Medium/Low) 7. **Present the plan** and WAIT for your explicit confirmation

Input Modes

| Input | Mode | Behavior | |---|---|---| | `path/to/name.prd.md` | PRD artifact mode | Read the PRD, pick the next pending delivery milestone or implementation phase, and write `.claude/plans/{name}.plan.md` | | Any other markdown path | Reference mode | Read the file as context and produce an inline plan | | Free-form text | Conversational mode | Produce an inline plan | | Empty input | Clarification mode | Ask what should be planned |

In PRD artifact mode, create `.claude/plans/` if needed. If the PRD contains a `Delivery Milestones` table, update only the selected row from `pending` to `in-progress` and set its `Plan` cell to the generated plan path. If the PRD uses the legacy `.claude/PRPs/prds/` format with `Implementation Phases`, read it without migrating paths.

Pattern Grounding

Before writing the plan, search the codebase for conventions the implementation should mirror. Capture the top example for each relevant category with file references:

| Category | What to capture | |---|---| | Naming | File, function, type, command, or script naming in the affected area | | Error handling | How failures are raised, returned, logged, or handled gracefully | | Logging | Levels, format, and what gets logged | | Data access | Repository, service, query, or filesystem patterns | | Tests | Test file location, framework, fixtures, and assertion style |

If no similar code exists, state that explicitly. Do not invent a pattern.

PRD Artifact Output

When called with a `.prd.md` file, write the plan to `.claude/plans/{kebab-case-name}.plan.md` using this structure:

# Plan: {Feature Name}

**Source PRD**: {path}
**Selected Milestone**: {milestone or phase name}
**Complexity**: {Small | Medium | Large}

## Summary
{2-3 sentences}

## Patterns to Mirror
| Category | Source | Pattern |
|---|---|---|
| Naming | `path:line` | {short description} |
| Errors | `path:line` | {short description} |
| Tests | `path:line` | {short description} |

## Files to Change
| File | Action | Why |
|---|---|---|
| `path` | CREATE / UPDATE / DELETE | {reason} |

## Tasks
### Task 1: {name}
- **Action**: {what to do}
- **Mirror**: {pattern to follow}
- **Validate**: {command that proves correctness}

## Validation
```bash
{project-specific validation commands}

Risks

| Risk | Likelihood | Mitigation | |---|---|---|

Acceptance

• [ ] All tasks complete
• [ ] Validation passes
• [ ] Patterns mirrored, not reinvented

After writing the artifact, report its path and WAIT for confirmation before writing code.

> **Visual review:** instead of asking for a typed confirmation, you can open the
> artifact in the browser Plan Canvas (`/plan-canvas`, or the `plan-canvas` skill):
> the user annotates the plan in place and clicks **Approve plan** or **Request
> changes**, which arrives as your confirmation signal.

## Example Usage

User: /plan I need to add real-time notifications when markets resolve

Assistant:

Implementation Plan: Real-Time Market Resolution Notifications

Requirements Restatement

• Send notifications to users when markets they're watching resolve
• Support multiple notification channels (in-app, email, webhook)
• Ensure notifications are delivered reliably
• Include market outcome and user's position result

Implementation Phases

Phase 1: Database Schema

• Add notifications table with columns: id, user_id, market_id, type, status, created_at
• Add user_notification_preferences table for channel preferences
• Create indexes on user_id and market_id for performance

Phase 2: Notification Service

• Create notification service in lib/notifications.ts
• Implement notification queue using BullMQ/Redis
• Add retry logic for failed deliveries
• Create notification templates

Phase 3: Integration Points

• Hook into market resolution logic (when status changes to "resolved")
• Query all users with positions in market
• Enqueue notifications for each user

Phase 4: Frontend Components

• Create NotificationBell component in header
• Add NotificationList modal
• Implement real-time updates via Supabase subscriptions
• Add notification preferences page

Dependencies

• Redis (for queue)
• Email service (SendGrid/Resend)
• Supabase real-time subscriptions

Risks

• HIGH: Email deliverability (SPF/DKIM required)
• MEDIUM: Performance with 1000+ users per market
• MEDIUM: Notification spam if markets resolve frequently
• LOW: Real-time subscription overhead

Estimated C