Ralph:Plan

# /ralph:plan - Create Implementation Plan

Analyze PRD or Change Request and create implementation plan with executable specs.

## Usage

/ralph:plan # Auto-detect input (PRD or CR) /ralph:plan --prd # Force PRD mode /ralph:plan --change-request # Force Change Request mode /ralph:plan --input custom.md # Custom input file

## Two Entry Points

| Source               | Input                      | Output             |
| -------------------- | -------------------------- | ------------------ |
| Greenfield (new app) | `docs/PRD.md`              | Full spec sequence |
| Brownfield (changes) | `docs/CHANGE-REQUEST-*.md` | CR-\* specs        |

## Prerequisites

- **Greenfield:** `docs/PRD.md` must exist (run `/ralph:discover` first)
- **Brownfield:** `docs/CHANGE-REQUEST-*.md` must exist (run `/ralph:change-request` first)

## Output

- `docs/IMPLEMENTATION_PLAN.md` - Overview with epics and tasks
- `.ralph-specs/*.md` - Executable spec files (this is what Ralph runs on VM)

## LANGUAGE SETTING

**FIRST: Detect language automatically**

```bash
LANG=$(grep -o '"language"[[:space:]]*:[[:space:]]*"[^"]*"' .ralph/config.json 2>/dev/null | cut -d'"' -f4)
echo "Language: ${LANG:-en}"

Use the detected language for ALL output (specs, plans, comments).

---

STEP 1: Detect Input Source

# Check for Change Request (most recent)
CR_FILE=$(ls -t docs/CHANGE-REQUEST-*.md 2>/dev/null | head -1)

# Check for PRD
PRD_FILE="docs/PRD.md"

if [ -n "$CR_FILE" ]; then
    echo "Found Change Request: $CR_FILE"
elif [ -f "$PRD_FILE" ]; then
    echo "Found PRD: $PRD_FILE"
else
    echo "No input found"
fi

Auto-detect logic:

1. If CHANGE-REQUEST-*.md exists → Change Request mode
2. Else if PRD.md exists → PRD mode
3. Else → Error

Detected input source:

1) Change Request: {filename} (brownfield)
2) PRD: docs/PRD.md (greenfield)
3) Neither found - need to run /ralph:discover or /ralph:change-request first

Using: {detected}

1) Continue with detected source
2) Switch to other source

Reply with number:

---

STEP 2: Choose Mode

How do you want to create specs?

1) Autonomous (YOLO) - I analyze PRD and create all specs, you review at the end
2) Interactive - We go through each epic/spec together

Reply with number:

---

PLANNING PHASES

For Change Requests (Brownfield)

If input is a Change Request, the planning is simplified:

1. Read CR document - Requirements and scope already defined
2. Verify specs from CR - CR should have suggested specs
3. Check completeness - Ensure all requirements have specs
4. Generate any missing specs - Fill gaps
5. Update IMPLEMENTATION_PLAN.md - Add CR section

CR specs are prefixed with CR-:

.ralph-specs/
├── 01-project-setup.md      # Original specs (if any)
├── 02-auth.md
├── CR-01-dark-mode.md       # Change Request specs
├── CR-02-theme-toggle.md
└── ...

→ Skip to "SPEC FILE FORMAT" section

---

For PRD (Greenfield)

Phase 1: ANALYZE PRD

📊 ANALYZING PRD

1. Identify all features from "Must Have (MVP)"
2. Group into logical epics (max 5-7 epics)
3. Identify dependencies between tasks
4. Order by dependency (what must come first?)

Output: Epic overview

---

Phase 2: BREAK DOWN EPICS

🔨 BREAKING DOWN EPICS

For each epic:

1. List all tasks needed
2. Ensure each task is atomic (one thing)
3. Add acceptance criteria from PRD
4. Identify E2E test for each

Rule: One task = one sentence without "and"

---

Phase 3: VERIFY COMPLETENESS

✅ VERIFYING COMPLETENESS

Completeness Loop:

For each spec:
  1. Läs spec
  2. Checka mot PRD:
     - Täcker denna spec PRD-kravet fullständigt?
     - Saknas edge cases?
     - Saknas error handling?
  3. Checka mot andra specs:
     - Finns alla beroenden?
     - Är ordningen rätt?
  4. Om luckor → iterera
  5. Annars → nästa spec

Check	Question
✅ PRD Coverage	Täcker specs ALLA must-have features?
✅ Dependencies	Är beroenden explicit?
✅ Testability	Har varje spec E2E test criteria?
✅ Atomicity	Är varje spec EN sak?
✅ Order	Är ordningen rätt (dependencies first)?

---

SPEC FILE FORMAT

KEEP SPECS MINIMAL - MAX 20 LINES

# {Task-name}

{1-2 sentences what to build}

## Requirements

- {Concrete requirement 1}
- {Concrete requirement 2}
- {Concrete requirement 3}

## E2E Test

Write test in `e2e/{feature}.spec.ts` that verifies:

- {what test should check}

## Done when

- [ ] Build passes
- [ ] E2E test passes
- [ ] {Specific verification}

IMPORTANT:

• No background/context - Claude reads the code
• No implementation details - Claude knows how
• Only WHAT, not HOW
• One spec = one focused task

---

SPEC STRUCTURE

.ralph-specs/
├── 01-project-setup.md   ← MUST include Playwright!
├── 02-database-schema.md
├── 03-auth-context.md
├── 04-login-page.md
├── 05-{feature}.md
└── ...

CRITICAL - 01-project-setup MUST contain:

• Vite + React + TypeScript setup (or chosen stack)
• Tailwind with design tokens from PRD
• Playwright installation (npx playwright install)
• playwright.config.ts
• e2e/smoke.spec.ts

⚠️ Without Playwright, Ralph's test-loop won't work!

---

EXAMPLE SPECS

Good spec (minimal):

# Auth Context

Create React context for authentication with Supabase.

## Requirements

- AuthProvider wrapper component
- useAuth hook (user, signIn, signOut, loading)
- Automatic session refresh on mount

## E2E Test

Write test in `e2e/auth.spec.ts` that verifies:

- Sign in redirects to home
- Sign out clears session

## Done when

- [ ] Build passes
- [ ] Can sign in/out via hook

Bad spec (too long):

# Auth Context

## Background

Authentication is