Create a PRD
A PRD is the scope contract for one change. Write it before the code, keep it under two screens, and update it when the plan changes.
Activate with @create-prd, /create-prd, or "write a PRD".
When to write one
- Three or more files will change
- The schema changes
- An architectural choice is being made (auth, hosting, data model)
- A bug took real investigation to diagnose
- The work will be referenced later as a migration guide or how-to
When to skip it
- A single file fix that is obvious from logs or types
- A typo, a CSS tweak, or a label change
- A copy change to markdown content
Location and naming
- Every PRD lives in
prds/. - File name:
prds/<feature-or-problem-slug>.md, kebab case. Example:prds/adding-email-auth.md. - Always
.md, never.prd. - Finished or sensitive PRDs move to
prds/archive/.
Template
Copy the full template from references/prd-template.md. The required parts:
# <Feature or problem, sentence case>
Created: YYYY-MM-DD HH:mm UTC
Last Updated: YYYY-MM-DD HH:mm UTC
Status: Draft | In Progress | Done
## Problem
## Root cause (bugs only)
## Proposed solution
## Files to change
## Edge cases
## Verification steps
## Out of scope
## Task completion log
Get the time from the system (date -u +"%Y-%m-%d %H:%M UTC"). Never invent it.
Filling it in
- Problem before solution. If the problem section is thin, the solution is a guess.
- For bugs, name the root cause: the line, query, or design choice. If it is unknown, say so and list the two likeliest candidates.
- Files to change is the scope. If a file not on the list needs to change, update the PRD first.
- Edge cases save the next session. Write down anything non obvious you found.
- Each verification step has an expected result, so someone else could run it.
- Out of scope is where extra ideas wait. Link an issue or a new PRD if they should happen later.
- The completion log is append only.
After writing it
- Add the tasks to
task.mdunder## To Doas checkable items, with the PRD path. - Share the PRD with the user if it has a real choice in it. Wait for an answer on that choice.
- Start building only once the plan is clear. Update
Last UpdatedandStatusas it moves.
Never
- Write a PRD for a one line change.
- Pad it. Two screens is plenty for most work.
- Mark it Done before its verification steps ran.