prd

Workflow

1. •

   Clarify the goal — Confirm the feature/goal with the user. Ask for:

   • •What problem does this solve? (not what to build — WHY to build it)
   • •Any known constraints (timeline, tech stack, dependencies)?
   • •Any prior art or related features?

   If the user provides enough context upfront, skip the interview and proceed.

2. •

   Research the codebase — Before writing, ground the PRD in reality:

   • •Glob for related code, configs, and existing docs
   • •Read relevant source files to understand current architecture
   • •Check for existing PRDs in __docs/prd/ to avoid duplication and maintain consistency
3. •

   Derive the feature name — Convert the feature/goal to kebab-case for the filename:

   • •"User Password Reset" → user-password-reset
   • •"Add Dark Mode Support" → dark-mode-support
   • •Strip verbs like "add", "implement", "create" — name the FEATURE, not the action
4. •

   Draft the PRD — Read references/template.md for the full MD structure, then write each section following these principles:

   Problem Statement — Write this FIRST. If you can't articulate the problem clearly, the PRD isn't ready. Ask the user for clarification instead of guessing.

   Goals vs Non-Goals — Non-goals are MORE important than goals. They prevent scope creep. For every goal, ask: "What's the adjacent thing someone might assume is included but ISN'T?"

   Functional Requirements — Number every requirement (FR-1, FR-2...). Each MUST be independently testable. If a requirement contains "and", split it into two.

   Acceptance Criteria — Write these as pass/fail checks. Use "Given/When/Then" format. Every functional requirement MUST have at least one acceptance criterion.

   Open Questions — Don't fake certainty. If something is unclear, list it here. A PRD with honest open questions is better than one with fabricated answers.

File Splitting

Always split PRDs into multiple files to maintain readability and enable parallel editing:

1. •Create an index file — Main PRD file that references sub-files
2. •Split logically — Group related content into separate files
3. •Index file structure — Include problem statement, goals, non-goals, and links to sub-files

__docs/prd/
├── feature-name.md          # Index file
└── feature-name/            # PRD sub-directory
    ├── overview.md          # Problem, goals, non-goals
    ├── functional-reqs.md    # All FR-X requirements
    └── acceptance-criteria.md # All acceptance criteria

The index file MUST:

• •Contain the problem statement and executive summary
• •Link to all sub-files
• •Serve as the entry point for reading the PRD

Sprint Contracts

Use sprint contracts when a feature spans multiple phases or sprints. Each contract defines what "done" means for that sprint and serves as the negotiation point between the generator (builder) and evaluator (reviewer).

• •Exit criteria must be testable and unambiguous — the evaluator should verify them without knowing implementation details. Use Given/When/Then format.
• •Handoff artifacts are the structured state that carries between sprints (e.g., updated schema, live API endpoints, migration scripts). Name them explicitly so the next sprint has a known starting point.
• •Verification methods should be concrete: specific test commands, manual check steps, or endpoint assertions — not "verify it works."
• •Tie each sprint's scope to specific FR numbers for traceability back to the PRD.

Write the file

Write to a directory structure, not a single file:

• •__docs/prd/<feature-name>.md → Index file (with YAML frontmatter)
• •__docs/prd/<feature-name>/ → Sub-directory containing the parts

Frontmatter for PRD files — Every PRD index file should start with:

---
title: <feature-name in title case>
date: yyyy-mm-dd format
author: git config --get user.name (fallback to git config --get user.email)
---

Example: If the feature is user-password-reset, the frontmatter would be:

---
title: User Password Reset
date: 2026-03-30
author: John Doe
---

Report

Summarize what was created and flag any open questions that need resolution before implementation.

Example: User Password Reset PRD

Given the request: "We need to let users reset their passwords"

Step 1 — Clarify: Users currently have no self-service recovery.
         Support team handles ~50 reset requests/week manually.

Step 2 — Research: Read auth module, found existing session management
         in src/auth/. No existing reset flow. Uses JWT tokens.

Step 3 — Feature name: user-password-reset

Step 4 — Draft (abbreviated):

  Problem: Users who forget passwords must contact support,
  creating ~50 tickets/week and 24hr average resolution time.

  Goals:
  - Self-service password reset via email
  - Reduce support tickets for password resets by 90%

  Non-Goals:
  - Account recovery for deleted accounts
  - Password reset via SMS (future phase)
  - Changing password policies or complexity rules

  Functional Requirements:
  - FR-1: System sends a reset email with a unique, time-limited token
  - FR-2: Reset tokens expire after 1 hour
  - FR-3: Reset tokens are single-use

  Acceptance Criteria (for FR-1):
  - Given a registered email, when the user requests a reset,
    then an email with a reset link is sent within 60 seconds.
  - Given an unregistered email, when the user requests a reset,
    then the same success message is shown (no email enumeration).

  Open Questions:
  - Should we invalidate existing sessions on password reset?
  - What's the rate limit for reset requests per email?

Step 5 — Write to:
  - __docs/prd/user-password-reset.md (index file with frontmatter)
  - __docs/prd/user-password-reset/overview.md
  - __docs/prd/user-password-reset/functional-reqs.md
  - __docs/prd/user-password-reset/acceptance-criteria.md

Writing Good Requirements — Common Mistakes

Constraints

• •NEVER invent requirements — if context is insufficient, list items under Open Questions
• •NEVER specify implementation details in functional requirements (that's for tech design)
• •NEVER skip Non-Goals — they are the most valuable section for preventing scope creep
• •ALWAYS number functional requirements (FR-1, FR-2...) for traceability
• •ALWAYS write acceptance criteria as testable pass/fail conditions
• •ALWAYS split PRDs into multiple files (index + sub-directory)
• •ALWAYS include YAML frontmatter in the index file
• •ALWAYS write index file to __docs/prd/<feature-name>.md
• •ALWAYS write sub-files to __docs/prd/<feature-name>/