pdd

Prompt-Driven Development

Overview

Transform a rough idea into a detailed design with an implementation plan. The process is iterative: clarify requirements, research, design, plan — moving between phases as needed.

Important Notes

These rules apply across ALL steps:

• User-driven flow: Never proceed to the next step without explicit user confirmation. At each transition, ask the user what they want to do next.
• Iterative: The user can move between requirements clarification and research at any time. Always offer this option at phase transitions.
• Record as you go: Append questions, answers, and findings to project files in real time — don't batch-write at the end.
• Mermaid diagrams: Include diagrams for architectures, data flows, and component relationships in research and design documents.
• Sources: Cite references and links in research documents when based on external materials.
• Planning only: This SOP produces planning artifacts. You MUST NOT implement code, run containers, execute scripts, or begin any implementation work. If the user wants implementation, direct them to ralph run.

Parameters

• rough_idea (required): The initial concept or idea to develop
• project_dir (optional, default: specs/{task_name}/): Base directory for all artifacts. {task_name} is derived as kebab-case from the idea (e.g., "build a rate limiter" → rate-limiter). Aligns with Ralph's spec-driven pipeline.

Constraints:

• You MUST ask for all required parameters upfront in a single prompt
• You MUST support multiple input methods: direct text, file path, URL
• You MUST derive task_name from the rough idea as kebab-case
• You MUST NOT overwrite an existing project directory — ask for a new path if it already has contents

Steps

1. Create Project Structure

Create the directory and initial files:

• {project_dir}/rough-idea.md — the provided rough idea
• {project_dir}/requirements.md — Q&A record (initially empty)
• {project_dir}/research/ — directory for research notes

Inform the user the structure feeds into Ralph's spec-driven presets.

Gate: You MUST NOT proceed to Step 2 until the user confirms the project structure is acceptable.

2. Initial Process Planning

Ask the user their preferred starting point:

• Requirements clarification (default)
• Preliminary research on specific topics
• Provide additional context first

Gate: You MUST wait for the user to choose before proceeding. You MUST NOT automatically start requirements clarification or research without explicit user direction.

3. Requirements Clarification

Guide the user through questions to refine the idea into a thorough specification.

Constraints:

• You MUST ask ONE question at a time — do not list multiple questions
• You MUST NOT pre-populate answers or batch-write Q&A to requirements.md
• You MUST follow this cycle for each question:
  1. Formulate and append question to requirements.md
  2. Present to user, wait for complete response
  3. Append answer to requirements.md
  4. Proceed to next question
• You MUST ask the user if requirements clarification is complete before moving on

Cover edge cases, user experience, technical constraints, and success criteria. Suggest options when the user is unsure.

Gate: You MUST NOT proceed to Research or Design until the user explicitly confirms requirements clarification is complete. You MUST offer the option to conduct research if questions arise that would benefit from additional information.

4. Research

Conduct research on technologies, libraries, or existing code to inform the design.

Constraints:

• You MUST propose a research plan to the user and incorporate their suggestions
• You MUST document findings in {project_dir}/research/ as separate topic files
• You MUST periodically check in with the user to share findings and confirm direction
• You MUST summarize key findings before moving on

Gate: You MUST NOT proceed to the Iteration Checkpoint until the user confirms research is sufficient. You MUST offer to return to requirements clarification if research uncovers new questions.

5. Iteration Checkpoint

Summarize the current state of requirements and research, then ask the user:

• Proceed to design?
• Return to requirements clarification?
• Conduct additional research?

Gate: You MUST NOT proceed to design without explicit user confirmation. You MUST support iterating between requirements and research as many times as needed.

6. Create Detailed Design

Create {project_dir}/design.md as a standalone document with these sections:

• Overview
• Detailed Requirements (consolidated from requirements.md)
• Architecture Overview
• Components and Interfaces
• Data Models
• Error Handling
• Acceptance Criteria (Given-When-Then format for machine verification)
• Testing Strategy
• Appendices (Technology Choices, Research Findings, Alternative Approaches)

Constraints:

• You MUST write the design as standalone — understandable without reading other files
• You MUST consolidate all requirements from requirements.md
• You MUST include an appendix summarizing research (technology choices, alternatives, limitations)
• You MUST review the design with the user and iterate on feedback

Gate: You MUST NOT proceed to the implementation plan until the user explicitly approves the design. You MUST offer to return to requirements or research if gaps are identified during design review.

7. Develop Implementation Plan

Create {project_dir}/plan.md — a numbered series of incremental implementation steps.

Guiding principle: Each step builds on previous steps, results in working demoable functionality, and follows TDD practices. No orphaned code — every step ends with integration. Core end-to-end functionality should be available as early as possible.

Constraints:

• You MUST include a checklist at the top of plan.md tracking each step
• You MUST format as "Step N:" with: objective, implementation guidance, test requirements, integration notes, and demo description
• You MUST ensure the plan covers all aspects of the design without duplicating design details

Gate: You MUST NOT proceed to the summary until the user reviews and approves the implementation plan.

8. Summarize and Present Results

Create {project_dir}/summary.md listing all artifacts, a brief overview, and suggested next steps. Present this summary in the conversation.

9. Offer Ralph Integration

Ask: "Would you like me to create a PROMPT.md for Ralph to implement this autonomously?"

If yes, create a concise PROMPT.md (under 100 lines) with:

• Objective statement
• Key requirements
• Acceptance criteria (Given-When-Then)
• Reference to specs/{task_name}/

Suggest the appropriate command:

• Full pipeline: ralph run --config presets/pdd-to-code-assist.yml
• Simpler flow: ralph run -c ralph.yml -H builtin:code-assist

If the user declines, acknowledge and conclude the session.

Gate: You MUST NOT run ralph run or begin any implementation. This SOP ends here. Implementation is a separate step the user initiates themselves.

Example

Input: "I want to build a template management feature for our internal tool — create, edit, share templates, generate documents with custom fields."

Output: A specs/template-management/ directory containing rough-idea.md, requirements.md, research/, design.md, plan.md, and summary.md — plus optionally a PROMPT.md for autonomous implementation.

Troubleshooting

Requirements stall: Suggest switching to a different aspect, provide examples, or pivot to research to unblock decisions.

Research limitations: Document what's missing, suggest alternatives with available information, ask user for additional context. Don't block progress.

Design complexity: Break into smaller components, focus on core functionality first, suggest phased implementation, return to requirements to re-prioritize.