Skip to main content

​
Product Requirements Documents (PRDs)

PRDs are the PM-owned functional specification for any new feature, significant enhancement, or user-facing change in Flux. They capture what to build and why — never how to build it.

​
What is a PRD?

A PRD is a Markdown/MDX document that defines:
  • The problem being solved and who has it
  • Success criteria — measurable outcomes that prove the work shipped
  • User stories with explicit Given / When / Then acceptance criteria
  • Functional requirements ranked Must-have / Should-have / Nice-to-have
  • UX requirements (wireframes, flows, descriptions)
  • Explicit out-of-scope items (prevents scope creep)
  • Open questions, dependencies, and risks
PRDs are deliberately lightweight. The goal is alignment, not exhaustive specification.

​
When to write a PRD

SituationWrite a PRD?
New user-facing feature✅ Yes
Significant enhancement to existing feature✅ Yes
Net-new persona, journey, or workflow✅ Yes
Bug fix❌ No — write a Cycle doc
Refactor with no behavior change❌ No — write a Cycle doc
Infrastructure / tooling change❌ No — write a Cycle doc (or RFC)
Tech-debt cleanup❌ No — write an RFC if the cleanup proposes a new pattern
Architectural decision (API shape, data model)❌ No — write an RFC

​
PRD numbering

  • Sequential: PRD-001, PRD-002, PRD-003, …
  • Numbers are never reused (even if a PRD is rejected or superseded)
  • Filenames use a descriptive slug: PRD-007-smart-scheduling.mdx

​
PRD lifecycle

draft  →  review  →  approved  →  in-progress  →  completed
                ↘
                  rejected | superseded
StatusMeaning
draftAuthor is iterating; not yet ready for stakeholder review
reviewOpen for stakeholder feedback (typically a 2–5 day window)
approvedStakeholders aligned; ready for engineering to schedule
in-progressA cycle is actively implementing this PRD
completedAll acceptance criteria met; feature shipped
rejectedStakeholders chose not to proceed (with rationale captured in the doc)
supersededReplaced by a newer PRD (linked in superseded_by)

​
How to create a PRD

  1. Open the Flux Specs site in Mintlify
  2. Navigate to PRDs → click New page → choose _template
  3. Edit the duplicated template in the WYSIWYG editor
  4. Save → Mintlify commits the new MDX file to GitHub on main
  5. Open a PR if you prefer review-before-merge (optional for drafts)

​
Option B — IDE / repo

  1. Copy docs/PRDs/_template.mdx to docs/PRDs/PRD-NNN-slug.mdx
  2. Fill in frontmatter and body
  3. Commit on a feature branch and open a PR for review
  4. Mintlify renders the new PRD as soon as it lands on main

​
Tips for AI-friendly PRDs

Claude Code reads PRDs as native files during cycle implementation. Mintlify Autopilot monitors PRDs for spec drift. Writing AI-friendly PRDs makes both work better:
  • Use structured headings — ## User Stories, ## Functional Requirements etc. so AI can navigate by section
  • Explicit Given / When / Then in acceptance criteria — AI infers test cases directly from this structure
  • Explicit out-of-scope — prevents AI from over-implementing
  • Avoid ambiguity — “fast” is ambiguous; “p95 < 500 ms” is not
  • Reference data and APIs by name — AI grounds claims against real schemas

​
Review process

  1. Author opens PR (or saves in Mintlify and opens PR for the resulting commit)
  2. Stakeholders comment on the PR or the Mintlify page
  3. Author iterates; when ready, they update status: approved and merge
  4. Engineering scopes a Cycle doc that references this PRD in source_prds

​
Relationship to RFCs and Cycles

PRD-007 (this kind of doc)
  ├── (sometimes) RFC-003 (architectural decision required)
  └── Cycle 215 (implementation plan and execution)
        └── PR #92  (the actual code change)
  • A PRD may inspire zero, one, or several RFCs (only if architectural decisions are needed)
  • A PRD typically maps to one Cycle but may span multiple
  • A Cycle without a source PRD is an internal change (refactor, infra, tooling)

​
See also