Ralph Plan

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

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

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 Modifications

/ralph-plan refactor the API to use dependency injection

Interview Phase:

• Q: "Which services should use DI?"
• A: "All services in src/services/"
• Q: "Testing implications?"
• A: "Should make mocking easier"

Research Phase:

• Explore finds: 8 service files, current instantiation patterns
• Librarian summarizes: Direct instantiation, no DI container

Plan Generated:

• 12 implementation steps
• Container setup, service refactoring

Approval: User selects "Request Changes" via AskUserQuestion, specifies "change step 5 to use factory pattern"

Updated Plan: Step 5 modified, re-presented with AskUserQuestion

Second Approval: User selects "Approve"

Output:

PRD finalized at .claude/plans/api-dependency-injection.md