PRD v3.1 Migration Guide

January 10, 2026 · View on GitHub

Purpose: Guide for transitioning existing v1 PRDs to the v3.1 format Estimated Time: 2-3 hours per PRD Difficulty: Moderate

Overview

This guide helps you upgrade existing Product Requirements Documents from v1 to v3.1. The migration focuses on adding the System Skeleton sections that bridge business requirements and technical implementation.

Why Migrate?

Benefit	Impact
Reduced developer questions	>50% fewer clarification requests
Faster implementation	Clear data model and business rules
Better test coverage	GWT format enables automation
Cleaner handoffs	Validation checklist catches gaps
Traceability	Feature→Test→Entity mapping

Migration Steps

Step 1: Create Section 0 - At-a-Glance (15 min)

Extract from your existing PRD:

Field	Where to Find It
Product Sentence	Vision statement (summarize to 1 sentence)
Primary User	Target Users section
Core Problem	Problem Statement
MVP Scope	MVP Features (top 3-5)
Non-Goals	Out of Scope section
Key Constraints	Technical Considerations
Success Metric	Success Metrics (pick #1)
Target Launch	Timeline section

Add Open Questions Table:

Review all "TBD", "TODO", or unclear items
Tag each as [BLOCKING] or [NON-BLOCKING]
Assign owners and due dates

| ID | Question | Owner | Tag | Due Date | Resolution |
|----|----------|-------|-----|----------|------------|
| Q-001 | What authentication provider? | [Name] | [BLOCKING] | [Date] | Pending |

Step 2: Create Section 2 - System Skeleton (60-90 min)

This is the most significant addition. You'll need to analyze your existing PRD to extract implicit information.

2.1 Glossary (15 min)

Find domain terms in your PRD:

Search for capitalized nouns (User, Project, Task)
Search for quoted terms ("active", "pending")
Look for acronyms (MVP, KPI, API)

For each term, document:

Definition (unambiguous)
Example (concrete)
Related terms

2.2 Conceptual Data Model (20 min)

Identify entities from your features:

What "things" does your system manage?
What are the relationships between them?
What states can each entity be in?

Example transformation:

Before (v1 Feature):

Users can create and manage projects

After (v3.1 Data Model):

| Entity | Description | Key Attributes | Relationships | Lifecycle |
|--------|-------------|----------------|---------------|-----------|
| User | System user | id, email, name | Has many Projects | active→suspended→deleted |
| Project | Work container | id, title, status | Belongs to User, Has many Tasks | draft→active→complete→archived |

2.3 UI Structure - Sitemap (15 min)

Map your user flows to routes:

What screens exist in your application?
Who can access each screen?
What are the primary actions on each?

Example:

| Route | View Name | Access Level | Primary Actions |
|-------|-----------|--------------|-----------------|
| /projects | Project List | Authenticated | Create, Search, Filter |
| /projects/:id | Project Detail | Owner, Member | Edit, Delete, Add Task |

2.4 Business Rules & State Machines (15 min)

Find implicit rules in your features:

Look for "only", "must", "cannot", "should"
Look for validation requirements
Look for conditional logic

Example transformation:

Before (v1 Feature):

Only project owners can delete projects

After (v3.1 Business Rule):

| Rule ID | Entity | Rule | Trigger | Error |
|---------|--------|------|---------|-------|
| BR-001 | Project | Only owner can delete | Delete action | "Unauthorized" (403) |

Create state machines for entities with "status" fields:

What states exist?
What triggers transitions?
What are the side effects?

2.5 External API Dependencies (10 min)

List all third-party services:

Authentication providers
Payment processors
Email services
Analytics platforms

For each, document:

Rate limits
Authentication method
Fallback strategy

2.6 Data Privacy & Compliance (10 min)

Classify your data:

What is PII? (email, name, phone)
What is financial? (payment tokens)
What is public? (project titles)

Check compliance requirements:

GDPR (if EU users)
CCPA (if California users)
HIPAA (if health data)

Step 3: Enhance Features with IDs and Types (30 min)

Add to each feature:

Feature ID: F-001, F-002, etc.
Type: CRUD, AUTH, INTEGRATION, ANALYTICS, WORKFLOW, NOTIFICATION, SEARCH, IMPORT/EXPORT
Touched Entities: Which entities from 2.2 does this feature affect?
Priority: P0 (MVP critical), P1 (MVP if time), P2 (post-launch), P3 (future)

Example transformation:

Before (v1):

## User Registration
As a visitor, I want to create an account so I can access the platform.
- Email validation
- Password requirements
- Email verification

After (v3.1):

#### F-001: User Registration

| Attribute | Value |
|-----------|-------|
| **Type** | AUTH |
| **Priority** | P0 |
| **Touched Entities** | User, VerificationToken |
| **Dependencies** | Email service |
| **Effort** | M (1-3 days) |

**User Story:**
> As a visitor, I want to create an account so I can access the platform.

**Acceptance Criteria (GWT):**

| AC ID | Given | When | Then |
|-------|-------|------|------|
| AC-001-01 | I'm on registration page | I submit valid email/password | Account is created, verification email sent |
| AC-001-02 | I'm on registration page | I submit invalid email | Error "Invalid email format" displays |
| AC-001-03 | I have verification email | I click verification link | Account is verified, redirected to login |

Step 4: Convert Acceptance Criteria to GWT (20 min)

For each feature, rewrite criteria in Given-When-Then format:

Before:

- Users can log in with email and password
- Invalid credentials show error message

After:

| AC ID | Given | When | Then |
|-------|-------|------|------|
| AC-002-01 | I'm on login page with valid credentials | I click "Sign In" | I'm redirected to dashboard |
| AC-002-02 | I'm on login page with invalid credentials | I click "Sign In" | Error "Invalid credentials" displays |

Step 5: Add Test Cases with IDs (15 min)

Create test cases linked to features:

| Test ID | Feature ID | Type | Description | Priority |
|---------|------------|------|-------------|----------|
| T-001 | F-001 | E2E | Happy path registration | P0 |
| T-002 | F-001 | E2E | Registration with invalid email | P0 |
| T-003 | F-001 | Integration | Email service sends verification | P1 |

Step 6: Complete Handoff Checklist (10 min)

Go through each item in Section 7:

Step 7: Add Preference Profile (10 min)

Fill in Appendix A JSON:

{
  "product": {
    "name": "Your Product",
    "version": "1.0.0",
    "type": "web-app"
  },
  "technology": {
    "frontend": {
      "framework": "react",
      "styling": "tailwind"
    },
    "backend": {
      "runtime": "node",
      "framework": "express"
    },
    "database": {
      "primary": "postgresql",
      "orm": "prisma"
    }
  }
}