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.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 promptYou MUST support multiple input methods: direct text, file path, URLYou MUST derive `task_name` from the rough idea as kebab-caseYou MUST NOT overwrite an existing project directory — ask for a new path if it already has contentsSteps
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 notesInform the user the structure feeds into Ralph's spec-driven presets.
2. Initial Process Planning
Ask the user their preferred starting point:
Requirements clarification (default)Preliminary research on specific topicsProvide additional context first3. 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 questionsYou MUST NOT pre-populate answers or batch-write Q&A to requirements.mdYou 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 onCover edge cases, user experience, technical constraints, and success criteria. Suggest options when the user is unsure.
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 suggestionsYou MUST document findings in `{project_dir}/research/` as separate topic filesYou MUST periodically check in with the user to share findings and confirm directionYou MUST summarize key findings before moving on5. Iteration Checkpoint
Summarize the current state of requirements and research, then ask the user:
Proceed to design?Return to requirements clarification?Conduct additional research?6. Create Detailed Design
Create `{project_dir}/design.md` as a standalone document with these sections:
OverviewDetailed Requirements (consolidated from requirements.md)Architecture OverviewComponents and InterfacesData ModelsError HandlingAcceptance Criteria (Given-When-Then format for machine verification)Testing StrategyAppendices (Technology Choices, Research Findings, Alternative Approaches)**Constraints:**
You MUST write the design as standalone — understandable without reading other filesYou MUST consolidate all requirements from requirements.mdYou MUST include an appendix summarizing research (technology choices, alternatives, limitations)You MUST review the design with the user and iterate on feedback7. 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 stepYou MUST format as "Step N:" with: objective, implementation guidance, test requirements, integration notes, and demo descriptionYou MUST ensure the plan covers all aspects of the design without duplicating design details8. 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 set up Ralph to implement this autonomously?"
If yes, create a concise PROMPT.md (under 100 lines) with:
Objective statementKey requirementsAcceptance 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 --config presets/spec-driven.yml`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.