---
roadcrew_template_name: "create-prd.md"
roadcrew_template_type: "command"
execution_mode: "auto-execute"
roadcrew_template_version: "v1.0"
roadcrew_last_updated: "2025-10-25"
roadcrew_min_version: "1.5.0"
roadcrew_license: "See LICENSE file in .roadcrew folder"
roadcrew_copyright: "Copyright (c) 2025 North Star Holdings, LLC"
spdx_license_identifier: "LicenseRef-RoadcrewLicense-1.0"
---

# create-prd

<!-- Usage: /create-prd [path/to/source-document.md] [--output path/to/output-prd.md] -->

You are transforming a source document (BRD, vision doc, narrative PRD, or even a detailed spec) into a ruthlessly concise, AI-parseable Product Requirements Document following `templates/prd.template.md`.

**Input Documents:** BRDs, vision docs, narrative PRDs, strategy documents, detailed specs (extract "what/why" only)
**Output:** Structured PRD optimized for 1:1 mapping to spec.template.md
**Template:** `templates/prd.template.md`

**Core Principles:**
1. **What/Why only** - No implementation details ("how" lives in spec)
2. **Strict length limits** - Every field has max words/bullets
3. **Table-driven** - User stories, journeys, mappings in tables
4. **Tight spec coupling** - Section 9 maps every requirement to spec section
5. **Atomic bullets** - No narrative prose except Problem Statement (≤50 words)

---

## WORKFLOW

### 0. PRE-FLIGHT CHECKS

**Read required context:**
- Source document (provided by user)
- `templates/prd.template.md` (the output format)
- `templates/spec.template.md` (downstream requirements)
- `templates/epic.template.md` (downstream requirements)
- `templates/release.template.md` (downstream requirements)

**Validate source document:**
- Contains business/user goals, requirements, or problem statements
- Has enough "what/why" content to extract
- If pure technical spec with no business context: WARN and extract what's available
- If BRD/vision: Perfect - extract product requirements
- If narrative PRD: Good - reformat to structured template

### 1. CHECK EXISTING OUTPUT FORMAT (NEW STEP)

**Predict output path:**
```
If user provides --output flag: Use that path
If not: Predict path as context/prds/[feature-id]-prd.md
```

**If output file already exists:**
```bash
# Check if file exists
if [ -f "$OUTPUT_PATH" ]; then
  echo "Checking existing PRD format..."
  
  # Read type from frontmatter
  TYPE=$(head -20 "$OUTPUT_PATH" | grep "^type:" | sed 's/.*: //')
  VERSION=$(head -20 "$OUTPUT_PATH" | grep "^version:" | sed 's/.*: //')
  
  if [ "$TYPE" = "prd" ]; then
    echo "✓ Output file is already a properly formatted PRD (v$VERSION)"
    echo ""
    echo "Options:"
    echo "1. Keep existing PRD (skip transformation)"
    echo "2. Overwrite with new PRD (from source document)"
    echo "3. Cancel"
    echo ""
    read -p "Choose [1/2/3]: " choice
    
    if [ "$choice" = "1" ]; then
      echo "Skipping transformation. PRD already up-to-date."
      exit 0
    elif [ "$choice" = "3" ]; then
      echo "Cancelled."
      exit 0
    fi
    # choice 2 continues to transformation
  else
    echo "⚠️  Output file exists but is NOT a PRD (type: $TYPE)"
    echo "This will be overwritten. Proceed? (yes/no)"
    read -p "> " confirm
    if [ "$confirm" != "yes" ]; then
      exit 0
    fi
  fi
fi
```

**If output doesn't exist:**
```
Continue to transformation (new PRD will be created)
```

### 2. EXTRACT METADATA

**From source document, extract:**
- Feature name (if not clear, derive from title)
- Feature ID (kebab-case: `feature-name`)
- Status (Draft by default)
- Version (1.0 by default)
- Related spec path (if mentioned, or predict: `../specs/[feature-id]-spec.md`)
- Related Epic (if mentioned)
- Creation date (today if new, original date if reformatting)
- Approvers (if mentioned, or leave as placeholders)

**Populate YAML frontmatter:**
```yaml
---
type: prd
feature: [Feature Name]
feature_id: [feature-id]
status: Draft
version: 1.0
created: 2025-10-24
updated: 2025-10-24
related_spec: ../specs/[feature-id]-spec.md
epic: [Epic link or TBD]
approvers: [product-owner, tech-lead]
---
```

### 3. BUSINESS & USER GOALS

#### 3.1 Business Objectives (≤3, each ≤15 words)
**Extract from source:**
- Look for: business goals, revenue targets, market objectives, strategic outcomes
- Convert narrative to bullets
- Each bullet: ≤15 words
- Focus on measurable business outcomes

**If not explicit in source:** Infer from context or problem statement

**Example:**
```markdown
- Reduce customer churn by 25% through improved onboarding experience
- Increase monthly recurring revenue by $50k with premium tier
- Expand market reach to enterprise customers (500+ employees)
```

#### 3.2 User Goals (≤4, each ≤15 words)
**Extract from source:**
- Look for: user needs, pain points being solved, desired capabilities
- Focus on user-centric outcomes
- Each bullet: ≤15 words

**Example:**
```markdown
- Complete onboarding in <5 minutes without technical assistance
- Track project progress across multiple repos from single dashboard
- Auto-classify issues to save 2-3 hours per release cycle
- Reduce context switching between planning and implementation tools
```

#### 3.3 Non-Goals / Out of Scope (≤3, each ≤12 words)
**Extract from source:**
- Look for: "not included", "future phases", "explicitly excluded"
- Critical for setting boundaries
- Each bullet: ≤12 words

### 4. PROBLEM STATEMENT (≤50 words)

**Synthesize from source into single paragraph:**
- Current state (what's broken/missing)
- User/business impact
- Context that motivates this work
- NO solutions or "how" - just the problem

**Structure:** "Currently, [users/business] experience [problem]. This results in [impact]. Context: [key constraint or driver]."

### 5. SUCCESS METRICS

#### 5.1 User Metrics (≤2, each ≤15 words)
**Extract or infer:**
- User-facing measurements of success
- Time saved, errors reduced, satisfaction increased
- Must be measurable

**Example:**
```markdown
- Onboarding completion rate increases from 60% to 85%
- Average time to create release decreases from 45min to 10min
```

#### 5.2 Business Metrics (≤2, each ≤15 words)
**Extract or infer:**
- Business impact measurements
- Revenue, cost savings, conversion, retention

**Example:**
```markdown
- 20% increase in paid tier conversion from free tier
- $15k monthly cost reduction in support tickets
```

#### 5.3 Technical Metrics (≤2, each ≤15 words)
**Extract or infer:**
- Technical health indicators
- Performance, reliability, scalability

**Example:**
```markdown
- Command execution time <2 seconds for 95th percentile
- Zero failed deployments due to missing dependencies
```

### 6. REQUIREMENTS

#### 6.1 Functional Requirements (max 6, ≤15 words each)
**Extract from source:**
- Core capabilities/features that must be delivered
- Each requirement gets ID: R1, R2, etc.
- Each: ≤15 words
- These MUST map to spec sections (section 9)

**CRITICAL:** Number these explicitly as R1-R6 for downstream mapping

**Example:**
```markdown
- R1: Install script creates project directories and copies commands to root
- R2: Mode detection identifies submodule, multi-repo, or template deployment automatically
- R3: License validation gates premium features via API key authentication
- R4: Commands auto-resolve paths based on detected deployment mode
- R5: Update mechanism pulls latest submodule without overwriting user content
- R6: Premium flags (--ai, --toc) require valid API key for execution
```

#### 6.2 Non-Functional Constraints (≤4, each ≤15 words)
**Extract or infer:**
- Performance, security, reliability, scalability requirements
- NOT the same as spec NFRs (those are technical details)
- Product-level constraints

**Example:**
```markdown
- Installation completes in under 10 seconds for typical projects
- Zero data loss on update (user content always preserved)
- Works offline for all free tier features (no network required)
- Supports repos up to 100k files without performance degradation
```

#### 6.3 Acceptance Criteria (≤5, each ≤12 words)
**Extract or create:**
- Product-level validation criteria
- Binary pass/fail tests
- Must be testable by product owner/stakeholders

**Example:**
```markdown
- AC1: New user installs and runs first command successfully
- AC2: Update preserves all user-created content without conflicts
- AC3: Premium feature prompts clear upgrade path with trial link
- AC4: Multi-repo mode creates issues in correct target repositories
- AC5: All commands work in both submodule and multi-repo modes
```

### 7. USER STORIES

**Extract from source or synthesize:**
- Convert use cases or scenarios into "As a/I want/So that" format
- 3-5 key user stories
- Keep each column concise (≤10 words)

**Format as table:**
```markdown
| ID  | As a              | I want to                      | So that I can              |
|-----|-------------------|--------------------------------|----------------------------|
| US1 | developer         | install Roadcrew as submodule  | avoid namespace conflicts  |
| US2 | tech lead         | update Roadcrew safely         | get new features without risk |
| US3 | enterprise admin  | manage multiple repos          | coordinate cross-service releases |
```

### 8. USER JOURNEY (≤5 steps, each ≤15 words)

**Extract from source or synthesize:**
- Key happy path through the feature
- Start to finish, user perspective
- Each action and result: ≤15 words

**Format as table:**
```markdown
| Step | Action                                      | Expected Result                    |
|------|---------------------------------------------|-----------------------------------|
| 1    | Add Roadcrew as git submodule               | .roadcrew/ folder appears         |
| 2    | Run install script                          | Commands copied, folders created  |
| 3    | Edit memory-bank/activeContext.md with product vision  | Vision file ready for commands    |
| 4    | Run /analyze-repo to detect tech stack      | tech-stack.md generated           |
| 5    | Run /guide-release to create first release  | current-release.md populated      |
```

### 9. NON-GOALS (≤3, each ≤12 words)

**Extract from source:**
- Features explicitly deferred to future releases
- Helps manage scope and expectations
- Each: ≤12 words

**Example:**
```markdown
- Visual UI dashboard (command-line only for v1.0)
- Windows native support (Mac/Linux only for v1.0)
- Automated dependency resolution between repos (manual config for v1.0)
```

### 10. IMPACT & DEPENDENCIES

**Extract from source:**
- Affected Systems: What systems/services will change
- Dependencies: What must exist first
- Risks: What could go wrong
- Related Links: Other docs, issues, PRs

**Keep each item concise** (≤30 words)

### 11. MAPPING TO SPEC (CRITICAL - TIGHT COUPLING)

**Create mapping table:**
- Each R1-R6 functional requirement maps to spec section
- Predict spec section numbers (2.1.1, 3.2, 4.1, etc.)
- If spec doesn't exist yet: predict logical structure
- If spec exists: reference actual sections

**Format:**
```markdown
| Functional Requirement                  | Spec Section |
|----------------------------------------|--------------|
| R1: Install script creates directories | 2.1.1        |
| R2: Mode detection identifies context  | 3.1          |
| R3: License validation gates features  | 4.2          |
| R4: Commands auto-resolve paths        | 3.2          |
| R5: Update mechanism preserves content | 5.1          |
| R6: Premium flags require API key      | 4.3          |
```

**CRITICAL:** This table is used by `/create-spec` to generate the inverse mapping (spec → PRD)

### 12. EDITOR INSTRUCTIONS

**Always include at bottom:**
```markdown
## Editor Instructions:
- Use bullets and tables exclusively; paragraphs only for Problem Statement (≤50 words).
- Each functional requirement (4.1) must map to spec section (9).
- Do not exceed length limits; AI and reviewers will reject oversized content.
- No implementation details—reference spec for all "how" questions.
- PRD answers "what/why", Spec answers "how".
- User stories and journeys provide context for spec issue breakdown.
```

### 13. VALIDATION & OUTPUT

**Before outputting, validate:**
- [ ] All length limits respected (no field exceeds max)
- [ ] Functional requirements (R1-R6) are numbered and mapped to spec sections
- [ ] User stories table has all 4 columns
- [ ] User journey table has all 3 columns
- [ ] Problem statement ≤50 words
- [ ] No implementation details (no "how", only "what/why")
- [ ] Mapping to spec table matches number of functional requirements

**Output format:**
- If `--output` flag provided: Write to that path
- If no flag: Write to `context/prds/[feature-id]-prd.md`
- Display summary: "Created PRD with N requirements, M user stories, [feature-id]-prd.md"

---

## EXAMPLE TRANSFORMATIONS

### Input: BRD (Monetization Strategy)
**Approach:**
- Extract: Business objectives (revenue targets), pricing tiers, conversion goals
- Synthesize: Functional requirements (license validation, feature gating, usage tracking)
- Create: User stories (free user, paid user, enterprise admin perspectives)
- Map to spec: License validation, API integration, usage dashboard

### Input: Narrative PRD (Submodule Isolation)
**Approach:**
- Extract: Problem statement (namespace conflicts), user goals (clean installation)
- Condense: Modes, installation flow → functional requirements
- Create: User journey (add submodule → install → use)
- Map to spec: Installation script, mode detection, path resolution

### Input: Detailed Spec (extract "what/why" only)
**Approach:**
- Reverse engineer: Technical solution → what user problem does this solve?
- Extract: Business context, user needs from spec intro/motivation
- Synthesize: Requirements from spec functional requirements section
- Create: User stories based on spec use cases
- Map: PRD requirements to existing spec sections

---

## SEPARATION OF CONCERNS

**PRD vs Spec - Crystal Clear Boundaries:**

**PRD Contains (WHAT/WHY):**
- Business objectives and user goals
- Problem statement and success metrics
- Functional requirements (what capabilities)
- User stories and journeys
- Product acceptance criteria
- Non-functional constraints (product-level)

**Spec Contains (HOW):**
- Technical design and architecture
- Data models, APIs, services
- Implementation approach and phases
- Issue breakdown with technical details
- Technical acceptance criteria
- Testing strategy

**PRD MUST NOT Include:**
- File names, function names, code structure
- Implementation approaches or algorithms
- Database schemas or API endpoints
- Technical architecture decisions
- Testing strategies or test plans

**If source contains technical details:** Extract only the "what/why", leave "how" for spec

---

## COST OPTIMIZATION

**Concise output patterns:**
- Tables over paragraphs (user stories, journeys, mappings)
- Bullets over prose (requirements, goals, metrics)
- Strict limits prevent verbosity
- "See spec" over duplication

**Expected savings:** 50-60% fewer tokens vs narrative PRDs

---

## GUARDRAILS

1. **Length Enforcement:**
   - If field exceeds limit: Truncate intelligently and warn
   - Better to be concise than verbose
   - Problem statement is ONLY field that can be paragraph (still ≤50 words)

2. **No Implementation Details:**
   - If source has "how" content: Strip it out
   - If user asks about "how": Redirect to spec
   - PRD is pure "what/why"

3. **Requirements Numbering:**
   - MUST number R1-R6 explicitly
   - MUST map each to spec section
   - Max 6 requirements (if more, suggest breaking into multiple PRDs/epics)

4. **User Story Quality:**
   - Must follow "As a/I want/So that" format
   - Each column ≤10 words
   - Must represent actual user value (not technical tasks)

---

**Behavior:**
- If invoked with file path (e.g., `/create-prd context/brds/monetization-strategy.md`), read that file and proceed
- If no path provided, ask user for source document path
- If `--output` flag provided, write to that path
- Always validate output against template structure before presenting
- If source is pure technical spec with no business context, extract what's available and WARN user