Ralph:Setup

---
description: Create or update a Ralph session from a spec/plan file (or feature description)
trigger: /ralph:plan
arguments: [plan-file]
---

# Ralph Plan/Session Assistant

Helps you create a PRD (prd.json) for the autonomous AI coding loop, optionally backed by a spec/plan file.

## Your Task

User provided: **$ARGUMENTS**

### If $ARGUMENTS is a file path (e.g., `plans/my-feature.md`):
1. Read the file using `@$ARGUMENTS` to include its contents
2. Interview the user about any missing **non-obvious** details (don't ask for things already in the spec)
3. Write the updated spec back to the same file (include all original content plus new clarifications)
4. Generate/update the session PRD from the spec

### If $ARGUMENTS is a feature description (not a file):
Guide them through creating a prd.json file as before.

### In both cases, create a prd.json file with:

1. Atomic tasks (fit in one context window, 5-15 minutes each)
2. Measurable acceptance criteria (objective, verifiable)
3. Clear priority ordering (dependencies expressed via priority numbers)
4. Appropriate validation commands for their project
5. **Optional workflow selection** (e.g., `test-coverage` for coverage-improvement sessions)

---

## Step 0: Solution Lookup (MANDATORY)

**Before analyzing the feature**, search for relevant existing solutions:

```bash
# Search docs/solutions/ for keywords from the feature description
grep -r "keyword1\|keyword2" docs/solutions/ --include="*.md" -l

Extract from matching solutions:

• Common gotchas to avoid
• Patterns that worked
• File locations of related code
• Known issues and their fixes

Include in PRD:

• Add relevant solution references to task notes fields
• Warn about known gotchas in acceptance criteria
• Reference successful patterns for similar work

Example searches:

• Feature: "user authentication" → grep -r "auth\|login\|session" docs/solutions/
• Feature: "API endpoint" → grep -r "api\|endpoint\|route" docs/solutions/
• Feature: "TypeScript migration" → grep -r "typescript\|migration\|types" docs/solutions/

This gives Ralph context about previously solved problems before starting.

---

Step 1: Analyze the Feature

Understand what the user wants to build:

• Break down into logical chunks
• Identify dependencies (what must come first)
• Estimate size of each chunk

Ask clarifying questions if needed:

• "What's the high-level goal?"
• "Are there existing files/components this should integrate with?"
• "What validation commands should run? (typecheck, test, lint, build)"
• "Which AI agent would you like to use? (claude, codex, opencode, cursor) - defaults to claude"
• "Which model would you like to use? (optional - leave blank to use agent's default)"

Step 2: Task Sizing Strategy

Right size for Ralph tasks:

• ✅ Single component (e.g., "Add LoginButton")
• ✅ Single API endpoint (e.g., "GET /users")
• ✅ Single utility function (e.g., "formatDate()")
• ✅ Single page/route (e.g., "/settings")
• ✅ Fix one specific bug
• ✅ Add one specific test case

Too big for one task:

• ❌ "Build entire auth system"
• ❌ "Implement complete dashboard"
• ❌ "Migrate all components to React"
• ❌ "Add comprehensive test suite"

Break down by:

• Components vs logic vs tests
• Features vs sub-features
• Dependencies (A must exist before B)

Step 3: Acceptance Criteria Rules

Good acceptance criteria (measurable, objective):

• "File X exists at path Y"
• "Component has props: { name: string, age: number }"
• "typecheck passes"
• "test: npm test -- test-name"
• "Endpoint returns 200 status"
• "UI displays: 'Success!' message"
• "Build completes with no errors"

Bad acceptance criteria (vague, subjective):

• "Users can log in"
• "UI looks good"
• "Performance is better"
• "Code is clean"

Verification examples:

// Good: Can be automatically checked
{
  "acceptanceCriteria": [
    "File exists: apps/web/src/components/LoginForm.tsx",
    "Has email and password fields (type='email', type='password')",
    "typecheck passes"
  ]
}

// Bad: Can't be automatically verified
{
  "acceptanceCriteria": [
    "Login form looks professional",
    "User experience is smooth",
    "Code is well-organized"
  ]
}

Step 4: Priority Ordering

Express dependencies via priority numbers:

{
  "userStories": [
    {
      "id": "AUTH-001",
      "title": "Create auth context",
      "priority": 1,
      "passes": false
    },
    {
      "id": "AUTH-002",
      "title": "Add login form",
      "priority": 2,
      "passes": false
    },
    {
      "id": "AUTH-003",
      "title": "Add logout button",
      "priority": 3,
      "passes": false
    }
  ]
}

In this example:

• AUTH-001 runs first (creates auth context)
• AUTH-002 runs second (login form depends on context)
• AUTH-003 runs third (logout button depends on context)

Step 5: Workflow Selection (Optional)

Ask the user if they want to use a workflow:

• Options: none (default PRD-driven), test-coverage, or other workflows in workflows/ directory
• If test-coverage selected:
  • Add workflow: "test-coverage" to prd.json
  • Add coverageCommand field (required, e.g., "pnpm test --coverage")
  • Add coverageTarget field (default: 100, but ask user for their target %)
  • Include a single long-lived story (e.g., COV-000) with acceptance criteria that enforce "one test per iteration" and "stop when target reached"
  • Set validationCommands.test to the same coverageCommand so validation re-checks coverage

Step 6: Agent and Model Selection

Ask the user for their preferences:

1. Agent selection:

   • Options: claude (default), codex, opencode, cursor
   • If not specified, default to claude
   • Explain briefly what each agent offers if user is unsure

2. Model selection:

   • If user wants a specific model, ask for it
   • Format depends on agent:
     • Claude: sonnet, opus, or full name li