indrasvat/prd-generator

PRD Generator with True Ralph Loop

Generate production-quality PRDs through interactive discovery, then implement autonomously using fresh Claude sessions (True Ralph Loop).

When to Use

• User says: "create PRD", "generate PRD", "new project", "write requirements", "plan feature"
• User wants to implement a PRD autonomously: "implement PRD", "start ralph loop", "autonomous mode"
• User needs to check progress: "PRD status", "what's left", "implementation progress"
• User returns after break/crash: "where was I", "resume", "continue from last session"

Phase 1: Discovery (Interactive Q&A)

Before generating a PRD, gather comprehensive requirements through adaptive, collaborative questioning.

Discovery Philosophy

Be a thought partner, not an interrogator.

Many users start with only a vague idea. Your job is to:

• Help them clarify and refine their thinking
• Offer concrete suggestions when they're unsure
• Validate rough ideas and help shape them
• Make "I don't know" a safe answer that leads somewhere useful

Handling Uncertainty

When a user says "I don't know" or seems unsure:

1. Offer 2-3 concrete options to choose from
2. Suggest what's typical for similar projects
3. Propose a sensible default they can accept or modify
4. Break big questions into smaller ones

Examples:

User: "I'm not sure what tech stack to use" → "Based on [what you've described], here are three approaches that would work well:

1. React + Node.js - Great for interactive UIs, huge ecosystem
2. Next.js - Good if you need SEO, built-in API routes
3. SvelteKit - Lighter weight, excellent performance What feels right, or should I explain the tradeoffs?"

User: "I don't know about scale requirements" → "Let's work backwards: Is this for personal use, a small team (<50 users), a growing startup (hundreds), or enterprise scale (thousands+)? For most new projects, starting with 'handles 100 concurrent users smoothly' is a reasonable baseline we can adjust."

User: "I have no idea what success looks like" → "That's normal at this stage! Let me suggest some metrics based on similar projects:

• For a tool: 'Users complete [core task] in under 2 minutes'
• For an app: 'Daily active users grows 10% week over week'
• For an API: '99.9% uptime, <200ms p95 latency' Which of these resonates, or what matters most to you?"

Question Flow

Ask questions ONE AT A TIME. Adapt based on answers. Be ready to suggest and guide.

Problem Space (Start Here - Be Exploratory)

1. Tell me about what you're trying to build

   • Start open-ended: "What's the idea?" or "What sparked this?"
   • If vague: "Paint me a picture - what does a user do with this?"
   • If stuck: Offer examples: "Is it more like [A], [B], or something different?"
   • Follow-up: "What's frustrating about how people handle this today?"

2. Who will use this?

   • If unsure: "Let's imagine your first 10 users - who are they?"
   • Offer personas: "Is this for developers, business users, consumers, or internal teams?"
   • Follow-up: "How technical are they? What tools do they already use?"

3. How will you know this is working?

   • If stuck: "If we check in 3 months from now, what would make you say 'this was worth it'?"
   • Offer metrics: "Would success be measured by time saved, revenue, user growth, or something else?"
   • Follow-up: "What's the minimum outcome that would make this a win?"

Technical Context (Offer Guidance)

4. What's the tech landscape?

   • If undecided: "I can suggest a stack based on your constraints. Any languages/frameworks you prefer or want to avoid?"
   • If existing code: "Point me to the repo or key files and I'll understand the patterns"
   • Proactively suggest: "Given [requirements], I'd recommend [X] because [reason]. Thoughts?"

5. Existing code or greenfield?

   • If existing: Explore architecture, patterns, conventions
   • If greenfield: "Great! We have flexibility. Any architectural patterns you like?"
   • Read key files to understand context before asking more questions

6. Scale and performance?

   • If unsure: "Let's estimate: how many users in month 1? Month 6? Year 1?"
   • Offer baselines: "For most new projects, designing for 1000 daily users is a safe start"
   • "Any hard requirements like 'must work offline' or 'real-time updates'?"

Scope & Constraints (Help Define Boundaries)

7. What should we explicitly NOT build?

   • If stuck: "What features would be 'nice to have later' vs 'must have now'?"
   • Suggest: "For a solid MVP, I'd suggest cutting [X] and [Y] for phase 2. Sound right?"
   • "What would be gold-plating vs essential?"

8. Non-functional requirements?

   • Offer checklist: "Let me run through some common ones:
     • Auth needed? (none / basic / OAuth / SSO)
     • Accessibility level? (basic / WCAG AA / AAA)
     • Compliance? (GDPR, HIPAA, SOC2, none)"
   • Suggest defaults: "For most projects, I'd recommend [X]. Any reason to go stricter?"

9. External dependencies?

   • Proactively identify: "Based on what you've described, you'll likely need [payment API / auth provider / etc]. Any preferences?"
   • "Any services you're already paying for that we should leverage?"

Verification (Guide Toward Testability)

10. Testing strategy?

    • If unsure: "I'll include a testing approach. Any existing test setup, or should I recommend one?"
    • Suggest: "For this type of project, I'd recommend [unit tests for core logic, integration tests for API, e2e for critical flows]"

11. What does 'done' look like?

    • If stuck: "Let's define the launch checklist together. What MUST work on day 1?"
    • Offer: "Typical launch criteria: [feature complete, tests pass, docs exist, deployed to prod]. Add or remove?"

12. Edge cases and failure modes?

    • Prompt thinking: "What's the worst thing that could happen? Data loss? Security breach? Downtime?"
    • Suggest: "Common edge cases for this type of project: [network failures, invalid input, concurrent edits]. I'll include handling for these."

Brainstorming Mode

If the user has only a vague idea, switch to brainstorming mode:

1. Explore the problem space: "Let's forget solutions for a moment. Tell me about the frustration or opportunity you've noticed."

2. Generate options: "Based on that, here are 3 different products you could build: [A], [B], [C]. Which excites you most?"

3. Refine iteratively: "Interesting! Let's explore [choice]. What if it also did [X]? Or would that be too much?"

4. Validate direction: "So the core idea is [summary]. Before we go deeper, does that capture it?"

Advanced Discovery Techniques

Five Whys - When the problem is unclear, keep asking "why" to find the root:

User: "I need a dashboard"
→ Why? "To see metrics"
→ Why do you need to see metrics? "To know if campaigns are working"
→ Why do you need to know that? "To stop wasting money on bad campaigns"
→ ROOT: The real need is campaign ROI visibility, not "a dashboard"

Ask About Past Behavior - People remember the past better than they predict the future:

• Instead of: "Would you use a feature that does X?"
• Ask: "Tell me about the last time you tried to do X. What happened? Where did you get stuck?"

Jobs to Be Done (JTBD) - Frame requirements around the "job" users hire the product to do:

• Template: "When [situation], I want to [motivation], so I can [outcome]"
• Example: "When I'm reviewing PRs late at night, I want to quickly see what changed, so I can approve without missing bugs"

Opportunity Solution Tree - Connect outcomes to opportunities to solutions:

Outcome: Increase user retention
  └── Opportunity: Users forget to return
        └── Solution A: Email reminders
        └── Solution B: Mobile push notifications
  └── Opportunity: Users don't see value quickly
        └── Solution A: Improved onboarding
        └── Solution B: Quick wins in first session

Pre-Mortem Technique (Shreyas Doshi) - Before building, imagine it failed:

• "It's 6 months from now and this project was a disaster. What went wrong?"
• Forces realistic risk assessment upfront

Encouraging Responses

Use encouraging language throughout:

• "That's a great starting point - let's build on it"
• "Good instinct. Here's how we might refine that..."
• "That's actually a common challenge. Here's what usually works..."
• "Perfect, that tells me a lot. Now I'm curious about..."
• "Not sure? No problem - let me offer some options..."

Completeness Check

Before generating PRD, verify each section has sufficient detail:

| Section | Required Info | |---------|--------------| | Problem | Clear pain points, user impact | | Users | Persona, technical level, workflow | | Success | Measurable metrics | | Tech | Stack, architecture decisions | | Scope | In/out of scope explicit | | Testing | Strategy defined | | Done | Acceptance criteria clear |

If any section is sparse, ask targeted follow-ups.

Phase 2: PRD Generation

Once discovery is complete, generate docs/PRD.md:

mkdir -p docs

Use the template in templates/PRD-TEMPLATE.md.

Critical PRD Requirements:

• Every task must have a checkbox: - [ ] Task description
• Group tasks into numbered phases (Phase 1, Phase 2, etc.)
• Each task ID format: Task X.Y (e.g., Task 1.1, Task 2.3)
• Include testable acceptance criteria for each user story
• Explicit "Out of Scope" section to prevent scope creep

Phase 3: PROGRESS.md Creation

Immediately after PRD, create docs/PROGRESS.md:

Use the template in templates/PROGRESS-TEMPLATE.md.

Critical PROGRESS.md Requirements:

• "Quick Context" section at top for instant orientation
• Current task clearly identified
• Recovery instructions for context loss scenarios
• Session history log for debugging

Phase 4: True Ralph Loop (Autonomous Implementation)

Why "True Ralph"?

The official Anthropic Ralph plugin uses a Stop hook that keeps Claude in the SAME session. This causes:

• Context rot from compaction over time
• "Ralph Wiggum state" - confusion from accumulated noise
• Degraded output quality after many iterations

True Ralph (Geoffrey Huntley's original vision) spawns FRESH Claude sessions:

• Each iteration has full context capacity
• No accumulated noise from previous attempts
• State persists only through files (PRD.md, PROGRESS.md, git)

Mode 1: External Script (Recommended)

When user wants to start Ralph loop, explain clearly:

True Ralph requires fresh Claude sessions OUTSIDE of this conversation.
This cannot run from within Claude - you need to run it from your terminal.

1. Open a NEW terminal window

2. Navigate to your project:
   cd [PROJECT_PATH]

3. Run the True Ralph Loop:
   ~/.claude/plugins/indrasvat-skills/skills/prd-generator/scripts/true-ralph-loop.sh -n [ITERATIONS]

4. Monitor progress:
   - Watch terminal output
   - Check docs/PROGRESS.md
   - View logs in .ralph/logs/

5. Stop gracefully: Ctrl+C

Before handing off:

1. Validate docs/PRD.md exists and has tasks
2. Ensure docs/PROGRESS.md exists
3. Verify git repo if applicable
4. Output the exact command to run

Mode 2: tmux Detach

If user prefers tmux and it's available:

# Check tmux availability
command -v tmux &>/dev/null || { echo "tmux not installed"; exit 1; }

# Get project name for session naming
PROJECT_NAME=$(basename "$(pwd)" | tr '[:upper:]' '[:lower:]' | tr ' ' '-')

# Spawn detached session
tmux new-session -d -s "ralph-${PROJECT_NAME}" \
  "~/.claude/plugins/indrasvat-skills/skills/prd-generator/scripts/true-ralph-loop.sh -n [ITERATIONS]"

echo "Ralph loop started in tmux session: ralph-${PROJECT_NAME}"
echo "Attach: tmux attach -t ralph-${PROJECT_NAME}"
echo "Kill:   tmux kill-session -t ralph-${PROJECT_NAME}"

Phase 5: Status Check

When user asks about progress:

echo "=== PRD Status ==="
if [ -f docs/PRD.md ]; then
    TOTAL=$(grep -c '^\- \[' docs/PRD.md 2>/dev/null || echo "0")
    DONE=$(grep -c '^\- \[x\]' docs/PRD.md 2>/dev/null || echo "0")
    PENDING=$(grep -c '^\- \[ \]' docs/PRD.md 2>/dev/null || echo "0")
    echo "Total tasks:     $TOTAL"
    echo "Completed:       $DONE"
    echo "Pending:         $PENDING"
    if [ "$TOTAL" -gt 0 ]; then
        PCT=$((DONE * 100 / TOTAL))
        echo "Progress:        $PCT%"
    fi
else
    echo "No PRD found at docs/PRD.md"
fi

echo ""
echo "=== Current State ==="
if [ -f docs/PROGRESS.md ]; then
    head -25 docs/PROGRESS.md
else
    echo "No PROGRESS.md found"
fi

Phase 6: Context Recovery

When user returns after a break, crash, or context loss:

1. Read PROGRESS.md first - contains quick context and current task
2. Read PRD.md - understand full requirements
3. Check git log - see recent commits
4. Check git status - see uncommitted changes

echo "=== Recovering Context ==="
echo ""
if [ -f docs/PROGRESS.md ]; then
    echo "Quick context from PROGRESS.md:"
    head -20 docs/PROGRESS.md
fi

echo ""
echo "Recent git activity:"
git log --oneline -5 2>/dev/null || echo "Not a git repo"

echo ""
echo "Uncommitted changes:"
git status -s 2>/dev/null || echo "Not a git repo"

Then summarize:

• Current phase and task
• What was last completed
• What should be done next

Best Practices

PRD Writing

• Use checkboxes (- [ ]) for ALL actionable items
• Group tasks logically into phases
• Each phase should be independently deployable
• Include "Out of Scope" to prevent creep
• Make acceptance criteria testable

PROGRESS.md Updates

• Update after EVERY task completion
• Move next pending task to "In Progress"
• Log blockers immediately
• Include relevant file paths and commit hashes

Ralph Loop Success

• Set realistic --max-iterations (start with 10-15)
• Ensure PRD tasks are granular (1-2 hour chunks)
• Each task should be independently verifiable
• Include test commands in PRD when applicable

Troubleshooting

"Claude keeps doing the same thing"

• Check PROGRESS.md - is the current task clearly marked?
• Regenerate PROGRESS.md with explicit task state
• Verify PRD tasks are actually checkboxed

"Ralph loop stops unexpectedly"

• Check .ralph/logs/ for the last iteration log
• Verify claude CLI is working: claude --version
• Check for syntax errors in PROGRESS.md

"Lost context after compaction"

• This is normal - use PROGRESS.md for recovery
• Run context recovery steps above
• The whole point of True Ralph is to handle this gracefully

See Also

• templates/PRD-TEMPLATE.md - Full PRD template
• templates/PROGRESS-TEMPLATE.md - Full progress template
• scripts/true-ralph-loop.sh - The True Ralph Loop script
• references/discovery-questions.md - Extended question bank