ring-writing-prds

name

ring:writing-prds

description

Writing a Product Requirements Document that explains to the squad WHAT is being built and WHY: problem, explicit scope in/out, functional requirements, and testable acceptance criteria. Gate 1 of ring:using-pm-team; runs after ring:researching-features and stays technology-free (no architecture, frameworks, or schemas). Use when starting a new feature or asked to plan or produce requirements. Skip when a validated PRD exists, for pure technical changes, or bug fixes.

PRD Creation — WHAT and WHY Before HOW

When to use

• Starting new product or major feature
• User asks to "plan", "design", or "architect"
• About to write code without documented requirements
• Asked to create PRD or requirements document

Skip when

• PRD already exists and validated → proceed to next gate
• Pure technical task without product impact → TRD directly
• Bug fix → systematic-debugging

Sequence

Runs after: ring:researching-features (Gate 0) Runs before: ring:mapping-feature-relationships (Gate 2, Large track) or ring:writing-trds (Gate 2, Small track)

The PRD is a squad-facing explanation of the product/feature being built: what it does, why it exists, what is in and out of scope, and how the squad knows it's done. It never answers HOW to build it (that's TRD) or WHERE components will live.

Mandatory Workflow

Phase	Activities
0. Load Research	Check docs/pre-dev/{feature}/research.md; reference codebase patterns and findings with file:line notation
1. Problem Definition	State the problem without solution bias; explain why it matters now; cite evidence from research.md
2. Requirements	Executive summary (3 sentences); functional requirements (WHAT the feature does); testable acceptance criteria per requirement; explicit scope boundaries (in/out)
3. Gate 1 Validation	Problem articulated; requirements address problem; acceptance criteria testable; scope explicit; zero technology content

Include in PRD

• Problem definition and why it matters
• Feature description: what it does, observable behavior
• Functional requirements (WHAT not HOW)
• Acceptance criteria (testable, per requirement)
• Scope boundaries (in/out explicitly)

Never Include in PRD

• Architecture diagrams or component design
• Technology choices (languages, frameworks, databases)
• Implementation approaches or algorithms
• Database schemas or API specifications
• Code examples or package dependencies
• Infrastructure needs or deployment strategies
• Personas, demographics, market analysis, go-to-market plans
• Adoption/satisfaction KPIs or business metric targets

Separation rules:

• Technology name → Dependency Map
• "How to build" → TRD
• Implementation detail → Plan tasks
• System behavior → TRD

Security Requirements Discovery (Functional Level)

Question	If Yes → Document
Feature handles user-specific data?	"Users can only access their own [data type]"
Different user roles with different permissions?	"Admins can [X], regular users can [Y]"
Need to identify who performed an action?	"Audit trail required for [action type]"
Integrates with other internal services?	"Service must authenticate to [service name]"
Regulatory requirements?	"Must comply with [regulation] for [data type]"

Include: "Only authenticated users can access", "Users can only view/edit their own records", "Admin approval required for [action]" Exclude: JWT tokens, Access Manager integration, OAuth2 flow — these go in TRD.

Operational Dashboard Discovery

For features involving data that accumulates over time (transactions, events, operations), ask:

AskUserQuestion: "Will an operator need a consolidated view of this feature's data to make decisions?"

• "Yes — Operational dashboard needed"
• "No — Infrastructure/backend only"
• "Not sure — Needs discussion"

If "Yes": Document in PRD under "Dashboard Requirements": who consumes it, decisions supported, key data shown, refresh cadence.

Gate 1 Validation Checklist

Category	Requirements
Problem Clarity	Problem stated without solution; why-now explained; grounded in research.md
Requirements	Every requirement describes observable behavior; acceptance criteria testable; all requirements trace to the problem
Scope	In-scope features explicit; out-of-scope stated; boundaries clear
Technology-Free	Zero technology names; zero implementation details; zero framework mentions

Gate Result: ✅ PASS → next gate | ❌ FAIL (re-work technical content or missing requirements)

Output

File: docs/pre-dev/{feature}/prd.md

After Gate 1 passes: Large track → ring:mapping-feature-relationships (Gate 2); Small track → ring:writing-trds (Gate 2). If the feature has UI, the orchestrator may recommend a standalone product-designer + ring:validating-ux-completeness run before the TRD (optional, not a gate).