amhuppert Write Product Requirements Document
Create or update a product requirements document that serves as the source of truth for product behavior and functionality.
Document Structure
The document must contain exactly three sections:
- App Summary - Brief overview (what, who, where)
- Design Principles - 3-5 high-level principles guiding the design
- Requirements - Comprehensive functional and non-functional requirements
App Summary
- Single paragraph describing core function
- Target users and use cases
- Platform and context (device types, environments)
- Keep under 10 bullet points total
Design Principles
- 3-5 principles maximum
- Each principle: short heading + 3-5 bullets
- Capture the "why" behind design decisions — rationale belongs here, not in the requirements
- Examples: Accessibility First, Cognitive Simplicity, Deliberate Safety
Requirements Section
Functional Requirements
Capture all user-facing features and behaviors, all UI screens and their states, all user interactions and their outcomes, data and content (categories, options, fixed values), and error handling and edge cases.
Organization:
- Group by feature area (FR1, FR2, FR3...)
- Sub-number within features (FR1.1, FR1.2...)
- Use descriptive headings
Non-Functional Requirements
Capture platform constraints (OS, device types, orientation), accessibility requirements (touch targets, contrast, cognitive load, motor control), interaction constraints (input methods, complexity limits), and performance and reliability expectations.
State Diagrams
Include at least one Mermaid state diagram showing state transitions: user interactions triggering state changes, relationships between independent state machines, and notes for important behaviors.
Example:
stateDiagram-v2
[*] --> StateA: User action
StateA --> StateB: Condition met
StateB --> StateA: User action
note right of StateA
Important behavior
or constraint
end note
User Interface
Describe screen layouts in text (no ASCII art), component visual design (colors, icons, labels where essential), component states (default, selected, disabled, etc.), and layout proportions where they affect functionality.
User Interactions
Document interaction sequences step-by-step, timing where it affects UX, what persists vs what clears, and state preservation across actions.
Scope and Level of Detail
Describe the product, not the implementation: leave out code files, component and class names, build or deployment information, technology stack specifics, and file structures. Also omit "excluded features" / "out of scope" sections, version numbers, and last-updated dates.
Document current behavior only — no alternatives, no future enhancements or roadmap. Within that scope, be complete: every user action and system response, every UI state and transition, every error condition, every persistence rule.
Include a style detail only when it is essential to functionality or accessibility — "YES button is green with checkmark icon" belongs because the color conveys meaning. Exclude implementation minutiae such as exact padding, font sizes, animation durations, or hex color values. Rule of thumb: if changing the detail would not meaningfully change functionality or user experience, leave it out.
Writing Style
- Use bulleted lists over prose; one concept per bullet
- Imperative for requirements ("App must...", "User can...")
- Declarative for states ("Button is green", "Sidebar appears")
- Optimize for AI agent consumption: concise, high information density, each section providing unique information
- Keep the document under 600 lines where possible; use Mermaid diagrams to replace lengthy text descriptions
Output
Save as PRODUCT_REQUIREMENTS.md in the project root or docs/ directory, formatted as Markdown with Mermaid diagrams.