Write PRD
Write PRDs grounded in what already exists. Greenfield repos get an interview-first flow; existing systems get a codebase audit first.
Workflow
1. Frame the request
Capture: user problem and desired outcome, affected actors and surfaces, constraints and non-goals, and whether this is net-new behavior, an extension, or a replacement. If the description is thin, ask for a detailed problem statement before exploring.
2. Audit the current system
Read enough code to answer:
- where the feature enters the system
- which modules already solve part of it
- existing patterns, contracts, and naming conventions
- tests, plans, or docs describing adjacent behavior
Verify the user's assertions against the code — treat missing evidence as uncertainty, not permission to invent.
3. Inventory reuse
Classify every capability the feature needs:
- Reuse: extend or compose as-is
- Modify: existing modules that need changes
- Net-new: does not exist yet
Never propose new infrastructure when a viable existing path exists.
4. Resolve decisions
Interview the user until the design is coherent: user-visible behavior and edge cases, schema impact, API/events/jobs, auth, rollout and failure modes, observability and testing. Sketch the major modules; prefer deep modules (simple, stable interfaces over lots of functionality) and confirm which get tests. Use grill-me if the proposal is still vague or risky.
5. Write the PRD
Use the template in REFERENCE.md. Include an extensive numbered user-story list (As an <actor>, I want <feature>, so that <benefit>), module boundaries, contracts, and testing strategy. No volatile file paths or code snippets — they go stale. If the user wants it tracked, file it as a GitHub issue via gh issue create.
6. Hand off
prd-to-plan to phase it; note open questions that block implementation.
Guardrails
- Call out assumptions separately from confirmed findings.
- If the repo is too large to inspect fully, state the sample used and confidence level.
References
- REFERENCE.md — PRD template, repo-audit checklist, reuse inventory format, decision prompts.