/ralph-plan

name: ralph-plan
description: "Structured PRD generation with interview, research, and approval workflow. Triggers on: '/ralph-plan <topic>', 'create prd', 'generate prd', 'plan this'. Creates comprehensive Product Requirements Document via interview and research."
allowed-tools:
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - Bash
  - Agent
  - TodoWrite
  - AskUserQuestion

Ralph Plan Skill

Structured PRD generation. Interview, research, plan, approve.

What is Ralph Plan?

Ralph Plan creates comprehensive Product Requirements Documents through a deliberate process:

1. **Interview Phase** - Understand requirements through focused questions 2. **Research Phase** - Analyze codebase via Explore/librarian 3. **Planning Phase** - Generate structured plan with clear steps 4. **Approval Gate** - User reviews, modifies, and approves the final PRD

The result is a battle-tested plan ready for implementation by any method the user chooses.

When This Skill Activates

| Category | Trigger Phrases | |----------|-----------------| | **Start planning** | `/ralph-plan <topic>`, `create prd`, `generate prd`, `plan this` | | **Check status** | `ralph-plan status` | | **Resume** | `resume ralph-plan` |

---

Workflow

Phase 1: Planning

Create a structured plan through interview and research.

Step 1: Initialize Draft

Create draft at `.claude/plans/drafts/{topic-slug}.md` with template:

# Planning Draft: {topic}

## Status
Phase: Interview
Started: {timestamp}

## Requirements
- [to be captured from interview]

## Decisions
- [choices made during interview]

## Research Findings
- [results from Explore/librarian]

## Open Questions
- [unanswered items]

Step 2: Interview

Conduct focused interview (3-5 questions based on complexity):

**Core Questions:** 1. "What problem does this solve?" (understand context) 2. "What's the scope - minimal viable vs complete?" (set boundaries) 3. "Any constraints, non-goals, or things to avoid?" (define exclusions)

**Follow-up Questions (as needed):**

• Technical approach preferences
• Dependencies on other work
• Success criteria

Update draft after each answer.

Step 3: Research

Research the codebase before finalizing:

Agent: Explore
Task: Find relevant files for {topic}
Expected: List of files that will be affected

Agent: oh-my-claude:librarian
Task: Read and summarize key files
Expected: Summary of current implementation patterns

Add findings to draft under "## Research Findings".

Step 4: Generate Plan

Transform draft into structured plan with these sections:

# Plan: {topic}

## Context
[Why this plan exists, what problem it solves]

## Objectives

### Must Have
- [required outcomes]

### Must NOT
- [explicit exclusions and constraints]

## Implementation Steps
1. [Step with specific file references]
2. [Step with specific file references]
3. ...

## Files to Modify
| File | Changes |
|------|---------|
| `path/to/file.ts` | [what changes] |

## Acceptance Criteria
- [ ] [Testable criterion]
- [ ] [Testable criterion]
- [ ] [Testable criterion]

---

Phase 2: Approval Gate

**User must review and approve the plan before finalization.**

Present the Plan

1. Display the complete plan summary to the user 2. Use `AskUserQuestion` tool for approval:

{
  "questions": [{
    "question": "How would you like to proceed with this PRD?",
    "header": "PRD Status",
    "options": [
      {"label": "Approve", "description": "Finalize and save the PRD"},
      {"label": "Request Changes", "description": "Modify specific sections"},
      {"label": "Cancel", "description": "Abort and keep draft"}
    ],
    "multiSelect": false
  }]
}

**CRITICAL**: You MUST use the `AskUserQuestion` tool for approval. Do NOT output text prompts asking the user to "reply with" something.

Handle User Response

| User Response | Action | |---------------|--------| | "Approve" | Finalize PRD (move to final location) | | "Request Changes" | Ask what to change, update plan, re-present with `AskUserQuestion` | | "Cancel" | Keep draft, do not finalize | | "Other" (custom text) | Interpret and act accordingly, then re-prompt if needed |

**Do NOT interpret ambiguous responses as approval.** If unclear, re-prompt with `AskUserQuestion`.

On Approval

1. Move plan from draft to final location:

   .claude/plans/drafts/{topic-slug}.md  -->  .claude/plans/{topic-slug}.md

2. Delete the draft file

3. Report completion:

   PRD finalized at .claude/plans/{topic-slug}.md

   Next steps:
   - Review the plan at your convenience
   - Implement manually, or use your preferred automation
   - Reference the acceptance criteria to track progress

---

Status Checking

When user says `ralph-plan status`:

Ralph Plan Status
=================

**Plan:** {topic}
**Phase:** Interview | Research | Draft Complete | Awaiting Approval | Finalized

--- Plan Location ---
Draft: .claude/plans/drafts/{topic-slug}.md
Final: .claude/plans/{topic-slug}.md (if finalized)

--- Plan Contents ---
Steps: {total}
Acceptance Criteria: {total}
Files Affected: {count}

---

Examples

Example 1: Feature Implementation PRD

/ralph-plan implement user authentication with JWT

**Interview Phase:**

• Q: "What problem does this solve?"
• A: "Users need to log in securely"
• Q: "What's the scope?"
• A: "Basic login/logout with token refresh"
• Q: "Any constraints?"
• A: "Must use existing user model, no OAuth"

**Research Phase:**

• Explore finds: `src/models/User.ts`, `src/routes/index.ts`
• Librarian summarizes: Uses Express, no existing auth middleware

**Plan Generated:**

• 6 implementation steps
• 4 files to modify
• 4 acceptance criteria

**Approval:**

Plan presented to user with `AskUserQuestion` tool. User selects: "Approve"

**Output:**

PRD finalized at .claude/plans/user-authentication-jwt.md

---

Example 2: Refactoring PRD with Modific