Ring:pre Dev Prd Creation

PRD Creation - Business Before Technical

Foundational Principle

Business requirements (WHAT/WHY) must be fully defined before technical decisions (HOW/WHERE).

Mixing business and technical concerns creates:

• Requirements that serve implementation convenience, not user needs
• Technical constraints that limit product vision
• Inability to evaluate alternatives objectively
• Cascade failures when requirements change

The PRD answers: WHAT we're building and WHY it matters to users and business. The PRD never answers: HOW we'll build it or WHERE components will live.

Mandatory Workflow

Explicit Rules

✅ DO Include in PRD

Problem definition and user pain points, user personas (demographics, goals, frustrations), user stories with acceptance criteria, feature requirements (WHAT not HOW), success metrics (adoption, satisfaction, KPIs), scope boundaries (in/out explicitly), go-to-market considerations

❌ 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, system integration patterns

Separation Rules

1. If it's a technology name → Not in PRD (goes in Dependency Map)
2. If it's a "how to build" → Not in PRD (goes in TRD)
3. If it's implementation → Not in PRD (goes in Tasks/Subtasks)
4. If it describes system behavior → Not in PRD (goes in TRD)

Rationalization Table

Security Requirements Discovery (Business Level)

During PRD creation, identify if the feature requires access control:

What to include in PRD:

• ✅ "Only authenticated users can access this feature"
• ✅ "Users can only view/edit their own records"
• ✅ "Admin approval required for [action]"
• ✅ "Must track who performed each action"

What NOT to include in PRD:

• ❌ "Use JWT tokens" (technology choice → TRD)
• ❌ "Integrate with Access Manager" (architecture → TRD)
• ❌ "OAuth2 flow" (protocol choice → TRD)

Note: The TRD (Gate 3) will translate these business requirements into authentication/authorization architecture patterns. For Go services, refer to golang.md → Access Manager Integration section during TRD creation.

Red Flags - STOP

If you catch yourself writing or thinking any of these in a PRD, STOP:

• Technology product names (PostgreSQL, Redis, Kafka, AWS, etc.)
• Framework or library names (React, Fiber, Express, etc.)
• Words like: "architecture", "component", "service", "endpoint", "schema"
• Phrases like: "we'll use X to do Y" or "the system will store data in Z"
• Code examples or API specifications
• "How we'll implement" or "Technical approach"
• Database table designs or data models
• Integration patterns or protocols

When you catch yourself: Move that content to a "technical notes" section to transfer to TRD later. Keep PRD pure business.

Data Source Discovery (Frontend-only Features)

⛔ MANDATORY: If feature is frontend-only (uses existing backend APIs), this section MUST be completed.

When to Apply

Check research.md frontmatter for topology:

topology:
  scope: frontend-only  # ← This triggers data source discovery

Step 1: Identify Existing APIs

Document all existing APIs the feature will consume:

## Data Sources

### Existing Backend APIs

| API | Endpoint Pattern | Description | Documentation |
|-----|------------------|-------------|---------------|
| User API | /api/v1/users/* | User management | link to docs |
| Orders API | /api/v1/orders/* | Order operations | link to docs |

### API Capabilities Needed

| User Story | Required Capability | Available API | Gap? |
|------------|---------------------|---------------|------|
| US-001 | Get user profile | GET /users/:id | No |
| US-002 | List user orders | GET /orders?userId= | No |
| US-003 | Export order PDF | None | Yes - needs BFF |

Step 2: Identify API Gaps

If user story requires capability not available in existing APIs:

Step 3: Document in PRD

Add to PRD under "Technical Context" section:

## Technical Context (Frontend-only)

**Data Source Type:** Existing Backend APIs

**Available APIs:**
- User API (v1) - user management operations
- Orders API (v1) - order CRUD operations

**API Gaps Identified:**
- [ ] No endpoint for aggregated dashboard data → BFF needed
- [ ] PDF export not available → Backend enhancement OR BFF generation

**BFF Requirements:** [None | Aggregation | Transformation | Both]

Rationalization Table for Data Source Discovery

Gate 1 Validation Checklist

Gate Result: ✅ PASS → UX Validation → Feature Map | ⚠️ CONDITIONAL (address gaps) | ❌ FAIL (return to discovery)

Phase 4: UX Validation + Wireframes

After PRD passes Gate 1 validation, dispatch product-designer for UX validation:

Task(
  subagent_type="ring:product-designer",
  model="opus",
  prompt="Validate PRD at docs/pre-dev/{feature}/prd.md against user needs. Mode: ux-validation.

  UI Configuration (from pre-dev command):
  - UI Library: {ui_library}  // e.g., shadcn/ui, Chakra UI, or auto-detected
  - Styling: {styling}        // e.g., TailwindCSS, CSS Modules, or auto-detected

  Create ux-criteria.md with: problem validation status, refined personas, UX acceptance criteria (functional, usability, accessibility, responsive).

  If feature has UI components, also create wireframes/ directory with low-fidelity prototypes using the specified UI library components and styling approach."
)

IMPORTANT: Pass UI Configuration to product-designer

The UI Library and Styling choices (from /pre-dev-feature or /pre-dev-full questions) MUST be passed to product-designer:

• If user selected a library → Use that library's component names in wireframes
• If auto-detected from package.json → Use the detected library
• If "Custom components only" → Use generic component names

This ensures wireframes reference real components that will be available during implementation.

UX Validation Outputs:

• docs/pre-dev/{feature}/ux-criteria.md - UX acceptance criteria
• docs/pre-dev/{feature}/wireframes/ - Low-fidelity prototypes (if feature has UI)
  • {screen-name}.yaml - YAML wireframe specification per screen
  • user-flows.md - User flow diagrams with state transitions

UI Detection Rule: If PRD contains any of these, feature HAS UI and wireframes are REQUIRED:

• User stories mentioning: "see", "view", "click", "navigate", "page", "screen", "button", "form"
• Features involving: login, dashboard, settings, profile, reports, notifications
• Any user-facing interaction

UX Validation Checklist:

Wireframe YAML Format:

screen: Screen Name
route: /path
layout: layout-type
components:
  - id: component-id
    type: component-type
    # ... component specs
states:
  default: { ... }
  loading: { ... }
  error: { ... }
responsive:
  mobile: { ... }
  desktop: { ... }
accessibility:
  keyboard: [ ... ]
  screen-reader: [ ... ]

Document Placement (based on topology.structure)

prd.md placement:

ux-criteria.md and wireframes/ placement:

Why frontend path for UX docs? UX criteria and wireframes are consumed by frontend engineers. Placing them in the frontend module/repo ensures they are discoverable where they'll be used.

Directory creation for multi-module:

# Read topology from research.md frontmatter
# Create appropriate directories:

# For monorepo - frontend module
mkdir -p "{frontend.path}/docs/pre-dev/{feature}"

# For multi-repo - both repos for prd.md, frontend for UX
mkdir -p "{backend.path}/docs/pre-dev/{feature}"
mkdir -p "{frontend.path}/docs/pre-dev/{feature}"

If UX validation fails:

• Conflicting user needs → Return to Phase 1 (Problem Discovery)
• Missing persona details → Enrich PRD personas
• Unclear acceptance criteria → Iterate with product-designer
• Missing wireframes for UI feature → product-designer must create them

Common Violations

Confidence Scoring

Action: 80+ autonomous | 50-79 present options | <50 ask discovery questions

Design System Generation (For New Projects with UI)

MANDATORY: If feature has UI (Q4=Yes) AND project is new (no existing design system), generate design-system.md based on Q7-Q10 responses.

Trigger Conditions:

• Q4 = "Yes" (feature has UI)
• No existing globals.css with CSS variables OR no tailwind.config.* with custom colors
• Q7-Q10 were answered (not auto-detected from existing config)

design-system.md Template:

# Design System - {Feature Name}

## Configuration Source
- Accessibility: {Q7 response}
- Dark Mode: {Q8 response}
- Brand Color: {Q9 response}
- Typography: {Q10 response}

## Color Palette

### Primary
| Token | Light Mode | Dark Mode | Usage |
|-------|------------|-----------|-------|
| `--primary` | {derived from Q9} | {lighter for dark} | Main actions, links |
| `--primary-foreground` | #ffffff | {dark text} | Text on primary |
| `--primary-hover` | {darker shade} | {lighter shade} | Hover states |

### Neutral
| Token | Light Mode | Dark Mode | Usage |
|-------|------------|-----------|-------|
| `--background` | #ffffff | #0f172a | Page background |
| `--foreground` | #0f172a | #f8fafc | Primary text |
| `--muted` | #f1f5f9 | #1e293b | Secondary backgrounds |
| `--muted-foreground` | #64748b | #94a3b8 | Secondary text |
| `--border` | #e2e8f0 | #334155 | Borders, dividers |

### Semantic
| Token | Light Mode | Dark Mode | Usage |
|-------|------------|-----------|-------|
| `--success` | #16a34a | #22c55e | Success states |
| `--warning` | #ca8a04 | #eab308 | Warning states |
| `--error` | #dc2626 | #ef4444 | Error states |

## Contrast Validation ({Q7 level})

| Combination | Required Ratio | Actual | Pass |
|-------------|----------------|--------|------|
| foreground on background | {4.5:1 or 7:1} | {calculated} | ✅/❌ |
| primary on background | {4.5:1 or 7:1} | {calculated} | ✅/❌ |
| muted-foreground on background | {4.5:1 or 7:1} | {calculated} | ✅/❌ |

## Typography

### Font Stack
- Display: {Q10 choice}, sans-serif
- Body: {Q10 choice}, sans-serif
- Mono: 'Geist Mono', ui-monospace, monospace

### Scale
| Token | Size | Line Height | Usage |
|-------|------|-------------|-------|
| text-xs | 12px | 16px | Captions |
| text-sm | 14px | 20px | Secondary |
| text-base | 16px | 24px | Body |
| text-lg | 18px | 28px | Large body |
| text-xl | 20px | 28px | Small headings |
| text-2xl | 24px | 32px | Section headings |
| text-3xl | 30px | 36px | Page headings |

## Spacing Scale (4px base)

| Token | Value |
|-------|-------|
| spacing-1 | 4px |
| spacing-2 | 8px |
| spacing-3 | 12px |
| spacing-4 | 16px |
| spacing-6 | 24px |
| spacing-8 | 32px |

## Accessibility Requirements

- **Level:** {Q7 response}
- **Minimum contrast:** {4.5:1 for AA, 7:1 for AAA}
- **Focus indicators:** 2px solid ring required
- **Touch targets:** Minimum 44x44px
- **Reduced motion:** Respect prefers-reduced-motion

Color Derivation from Q9 (Brand Color):

Typography Mapping from Q10:

design-system.md Placement:

GATE BLOCKER: If feature has UI and project is new, design-system.md MUST exist before proceeding to TRD. The TRD will reference these tokens.

Output & After Approval

Outputs (paths depend on topology.structure):

1. ✅ Lock the PRD - no changes without formal amendment
2. ✅ Lock ux-criteria.md - defines UX acceptance for implementation
3. ✅ Lock wireframes/ - defines visual structure for ui-engineer
4. 🎯 Use all as input for Feature Map (ring:pre-dev-feature-map) or TRD (ring:pre-dev-trd-creation)
5. 🚫 Never add technical details retroactively
6. 📋 Keep business/technical strictly separated

The Bottom Line

If you wrote a PRD with technical details, delete it and start over.

The PRD is business-only. Period. No exceptions. No "just this once". No "but it's relevant".

Technical details go in TRD. That's the next phase. Wait for it.

Follow the separation. Your future self will thank you.