---
roadcrew_template_name: "create-release-docs.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-release-docs

<!-- Usage: /create-release-docs [subfolder-name] -->

You are creating a complete set of structured release documents (BRD → PRD → Spec) from narrative source material in `memory-bank/requirements/source-docs/[subfolder]/`.

**Input:** Narrative documents (strategy docs, requirements, technical details) in `memory-bank/requirements/source-docs/[subfolder]/`
**Output:** Structured BRD, PRD, and Spec in `memory-bank/requirements/brds/`, `memory-bank/requirements/prds/`, `memory-bank/requirements/specs/`
**Templates:** `templates/brd.template.md`, `templates/prd.template.md`, `templates/spec.template.md`

**Core Workflow:**
1. **Discover** source material in `memory-bank/requirements/source-docs/[subfolder]/`
2. **Generate BRD** → `memory-bank/requirements/brds/[feature-id]-brd.md` (business context)
3. **Generate PRD** → `memory-bank/requirements/prds/[feature-id]-prd.md` (product requirements, references BRD)
4. **Generate Spec** → `memory-bank/requirements/specs/[feature-id]-spec.md` (technical implementation, references BRD + PRD)

**Benefits:**
- Single command for complete release documentation
- Sequential generation ensures proper cross-referencing
- Each doc references previous docs (no duplication)
- Aggregates all source material for comprehensive coverage

---

## WORKFLOW

### 0. DISCOVER SOURCE MATERIAL

**If subfolder provided (e.g., `/create-release-docs submodule-isolation`):**
- Use that subfolder: `memory-bank/requirements/source-docs/submodule-isolation/`

**If no subfolder provided:**
- List all subfolders in `memory-bank/requirements/source-docs/`
- Display numbered list:
  ```
  Select narrative source folder:
  1. submodule-isolation/
  2. classification/
  3. monetization/
  4. [other folders...]
  
  Enter number or folder name:
  ```
- Wait for user selection
- Confirm selection: "Using source folder: memory-bank/requirements/source-docs/[selected]/"

**Read all narrative files in selected folder:**
```bash
# List all .md files recursively
find memory-bank/requirements/source-docs/[subfolder]/ -name "*.md" -type f
```

**Display discovered files:**
```
Found source material:
- monetization-strategy.md (414 lines)
- ai-prd.md (726 lines)
- submodule-isolation-spec.md (1240 lines)

Total: 3 files, ~2380 lines

Proceeding with document generation...
```

### 1. CHECK IF SOURCE FILES ARE ALREADY FORMATTED (NEW STEP)

**Before transforming, check each source file:**

For each .md file in `memory-bank/requirements/source-docs/[subfolder]/`:

```bash
# Check if file has proper YAML frontmatter with type field
for file in memory-bank/requirements/source-docs/[subfolder]/*.md; do
  TYPE=$(head -20 "$file" | grep "^type:" | sed 's/.*: //')
  
  if [ ! -z "$TYPE" ]; then
    echo "✓ Found pre-formatted document: $(basename $file) (type: $TYPE)"
  fi
done
```

**If any source files are properly formatted:**
```
Pre-formatted documents found:

1. license-enforcements.md
   - Type: brd
   - Status: Can be copied directly to memory-bank/requirements/brds/

2. amendments.md
   - Type: prd
   - Status: Can be copied directly to memory-bank/requirements/prds/

Transform remaining files? (yes/no)
```

**Offer quick copy options:**
```
Options:
1. Copy pre-formatted docs and transform narratives
2. Transform all (overwrite with transformed versions)
3. Cancel

Choose [1/2/3]:
```

**If user selects option 1 (copy pre-formatted):**
- For each pre-formatted file:
  - Determine output filename based on feature_id in frontmatter
  - Copy to appropriate folder: `memory-bank/requirements/brds/[feature-id]-brd.md`, etc.
  - Skip transformation for these files
  - Transform remaining narrative files

**Store which files were pre-formatted:**
```
Pre-formatted files copied:
- BRD: memory-bank/requirements/source-docs/license-enforcement/license-enforcements.md → memory-bank/requirements/brds/license-enforcement-brd.md
- PRD: memory-bank/requirements/source-docs/license-enforcement/amendments.md → memory-bank/requirements/prds/license-enforcement-prd.md

Remaining to transform:
- Narratives: [list of files that need transformation]
```

### 2. EXTRACT FEATURE ID AND METADATA

**Analyze source folder and files to determine:**
- Feature ID: Use subfolder name as default (e.g., `submodule-isolation`)
- Feature Name: Extract from first H1 heading across files or derive from folder name
- Business Owner: Look for "Owner:", "Author:", "Lead:" in files
- Version: Default to 1.0 unless specified
- Status: Default to Draft

**Aggregate all source content:**
- Read all .md files in folder
- Concatenate content (keep track of which file each section came from)
- This aggregated content is used for all three document generations

**Confirm with user:**
```
Feature ID: submodule-isolation
Feature Name: Submodule Isolation & Multi-Repo Support
Owner: [extracted or "product-owner"]
Version: 1.0

Continue? (Y/n)
```

### 3. GENERATE BRD (Business Requirements Document)

**Phase 1/3: Creating BRD**

**Predict output path:** `memory-bank/requirements/brds/[feature-id]-brd.md`

**Check if output already exists:**
```bash
# Check if file exists
if [ -f "memory-bank/requirements/brds/[feature-id]-brd.md" ]; then
  echo "Checking existing BRD format..."
  
  # Read type from frontmatter
  TYPE=$(head -20 "memory-bank/requirements/brds/[feature-id]-brd.md" | grep "^type:" | sed 's/.*: //')
  VERSION=$(head -20 "memory-bank/requirements/brds/[feature-id]-brd.md" | grep "^version:" | sed 's/.*: //')
  
  if [ "$TYPE" = "brd" ]; then
    echo "✓ BRD already exists in correct format (v$VERSION)"
    echo ""
    echo "Options:"
    echo "1. Keep existing BRD (skip generation)"
    echo "2. Regenerate BRD from narratives"
    echo "3. Cancel entire workflow"
    echo ""
    read -p "Choose [1/2/3]: " choice
    
    if [ "$choice" = "1" ]; then
      echo "Keeping existing BRD. Moving to PRD generation..."
      # Continue to PRD generation
    elif [ "$choice" = "3" ]; then
      echo "Cancelled."
      exit 0
    fi
    # choice 2 continues to regenerate
  else
    echo "⚠️  Output exists but is NOT a BRD (type: $TYPE)"
    echo "Overwrite? (yes/no)"
    read -p "> " confirm
    if [ "$confirm" != "yes" ]; then
      echo "Cancelled."
      exit 0
    fi
  fi
fi
```

**Read required templates:**
- `templates/brd.template.md`
- `templates/prd.template.md` (for downstream awareness)
- `templates/spec.template.md` (for downstream awareness)

**Execute BRD generation logic (from create-brd.md):**

1. **Extract Business Context:**
   - Executive Summary (≤40 words): Synthesize from all files
   - Market & Target Segments (≤4 bullets): Extract customer/user mentions
   - Revenue Streams (≤3 bullets): Extract monetization/pricing mentions
   - Differentiators (≤3 bullets): Extract competitive advantages

2. **Extract Business Goals (≤5, each ≤15 words):**
   - Look across all files for: revenue targets, market objectives, strategic outcomes
   - Prioritize financial and market success metrics

3. **Create Pricing Table (≤3 tiers):**
   - Extract pricing tiers mentioned across files
   - Synthesize if not explicit (Free, Starter, Enterprise)
   - Format: Tier, Price, Features (≤6 words), Audience

4. **Build GTM Roadmap (≤3 phases, each ≤20 words):**
   - Extract timeline/phases from files
   - Condense to 3 key market milestones

5. **Split Metrics (≤6 total across 3 categories):**
   - Product/Customer (2 max): MAU, conversion, retention
   - Financial (2 max): ARR, margin, CAC
   - Usage/Technical (2 max): Token usage, automation

6. **Create Risks Table (≤4 risks with mitigations):**
   - Extract business risks only (not technical)
   - Format: Risk, Mitigation

**Validate BRD:**
- [ ] All length limits respected
- [ ] Pricing table has ≤3 tiers
- [ ] Metrics split across 3 categories (2 per category)
- [ ] No product features (those go in PRD)
- [ ] No technical details (those go in Spec)

**Write BRD:**
- Output to: `memory-bank/requirements/brds/[feature-id]-brd.md`
- Display: "✅ BRD created: memory-bank/requirements/brds/[feature-id]-brd.md"

**Store BRD path for PRD/Spec cross-referencing:**
- `BRD_PATH = memory-bank/requirements/brds/[feature-id]-brd.md`

### 4. GENERATE PRD (Product Requirements Document)

**Phase 2/3: Creating PRD (references BRD)**

**Predict output path:** `memory-bank/requirements/prds/[feature-id]-prd.md`

**Check if output already exists:**
```bash
# Check if file exists
if [ -f "memory-bank/requirements/prds/[feature-id]-prd.md" ]; then
  echo "Checking existing PRD format..."
  
  # Read type from frontmatter
  TYPE=$(head -20 "memory-bank/requirements/prds/[feature-id]-prd.md" | grep "^type:" | sed 's/.*: //')
  VERSION=$(head -20 "memory-bank/requirements/prds/[feature-id]-prd.md" | grep "^version:" | sed 's/.*: //')
  
  if [ "$TYPE" = "prd" ]; then
    echo "✓ PRD already exists in correct format (v$VERSION)"
    echo ""
    echo "Options:"
    echo "1. Keep existing PRD (skip generation)"
    echo "2. Regenerate PRD from narratives"
    echo "3. Cancel workflow"
    echo ""
    read -p "Choose [1/2/3]: " choice
    
    if [ "$choice" = "1" ]; then
      echo "Keeping existing PRD. Moving to Spec generation..."
      # Continue to Spec generation
    elif [ "$choice" = "3" ]; then
      echo "Cancelled."
      exit 0
    fi
    # choice 2 continues to regenerate
  else
    echo "⚠️  Output exists but is NOT a PRD (type: $TYPE)"
    echo "Overwrite? (yes/no)"
    read -p "> " confirm
    if [ "$confirm" != "yes" ]; then
      echo "Cancelled."
      exit 0
    fi
  fi
fi
```

**Read inputs:**
- All narrative source files (from step 1)
- Generated BRD (from step 2) for context
- `templates/prd.template.md`

**Execute PRD generation logic (from create-prd.md):**

1. **Reference BRD for Business Context:**
   - **Don't duplicate** business goals, metrics, segments
   - **Add references** like: "See [BRD § 3 Business Goals](../brds/[feature-id]-brd.md#3-business-goals)"

2. **Extract Product Requirements:**
   - Business Objectives (≤3, each ≤15 words): Reference BRD or extract from PRD narrative
   - User Goals (≤4, each ≤15 words): Extract user-facing outcomes
   - Problem Statement (≤50 words): Synthesize from narrative
   - Functional Requirements R1-R6 (each ≤15 words): Extract "what" capabilities

3. **Create User Stories Table:**
   - Extract use cases from narrative
   - Format: As a / I want to / So that I can
   - 3-5 key stories

4. **Create User Journey Table (≤5 steps):**
   - Extract happy path from narrative
   - Format: Step, Action, Expected Result
   - Each action/result: ≤15 words

5. **Build PRD → Spec Mapping Table:**
   - For each R1-R6 requirement, predict spec section
   - Format: | R1: Brief | 2.1.1 |
   - This table is CRITICAL for spec generation

**Validate PRD:**
- [ ] All length limits respected
- [ ] R1-R6 requirements numbered and mapped to spec sections
- [ ] User stories table complete
- [ ] No technical implementation ("how")
- [ ] References BRD for business context (not duplicated)

**Write PRD:**
- Output to: `memory-bank/requirements/prds/[feature-id]-prd.md`
- Update `related_prd` in BRD to point to this PRD
- Display: "✅ PRD created: memory-bank/requirements/prds/[feature-id]-prd.md"

**Store PRD path for Spec cross-referencing:**
- `PRD_PATH = memory-bank/requirements/prds/[feature-id]-prd.md`

### 5. GENERATE SPEC (Technical Specification)

**Phase 3/3: Creating Spec (references BRD + PRD)**

**Predict output path:** `memory-bank/requirements/specs/[feature-id]-spec.md`

**Check if output already exists:**
```bash
# Check if file exists
if [ -f "memory-bank/requirements/specs/[feature-id]-spec.md" ]; then
  echo "Checking existing spec format..."
  
  # Read type from frontmatter
  TYPE=$(head -20 "memory-bank/requirements/specs/[feature-id]-spec.md" | grep "^type:" | sed 's/.*: //')
  VERSION=$(head -20 "memory-bank/requirements/specs/[feature-id]-spec.md" | grep "^version:" | sed 's/.*: //')
  
  if [ "$TYPE" = "spec" ]; then
    echo "✓ Spec already exists in correct format (v$VERSION)"
    echo ""
    echo "Options:"
    echo "1. Keep existing spec (skip generation)"
    echo "2. Regenerate spec from narratives"
    echo "3. Cancel workflow"
    echo ""
    read -p "Choose [1/2/3]: " choice
    
    if [ "$choice" = "1" ]; then
      echo "Keeping existing spec. Proceeding to validation..."
      # Continue to validation
    elif [ "$choice" = "3" ]; then
      echo "Cancelled."
      exit 0
    fi
    # choice 2 continues to regenerate
  else
    echo "⚠️  Output exists but is NOT a spec (type: $TYPE)"
    echo "Overwrite? (yes/no)"
    read -p "> " confirm
    if [ "$confirm" != "yes" ]; then
      echo "Cancelled."
      exit 0
    fi
  fi
fi
```

**Read inputs:**
- All narrative source files (from step 1)
- Generated BRD (from step 2) for constraints
- Generated PRD (from step 3) for requirements
- `templates/spec.template.md`

**Execute Spec generation logic (from create-spec.md):**

1. **Create PRD → Spec Mapping Table (Section 1):**
   - Use PRD's section 9 (PRD → Spec mapping)
   - Invert it to create Spec's section 1
   - Format: | PRD Req | Satisfied In Spec Section |

2. **Extract Technical Requirements:**
   - Functional Requirements (max 6): Map 1:1 from PRD R1-R6
   - Non-Functional Requirements (≤20 words each): Extract from technical narrative
     * Reference BRD for pricing constraints
     * Extract performance, security, reliability, scalability
   - Out of Scope (≤3 bullets, ≤12 words each): Extract deferred technical work

3. **Design Overview (≤100 words):**
   - Synthesize technical solution from narrative
   - Core approach, major system changes
   - NO "what/why" (that's in PRD)

4. **Architecture & Implementation:**
   - Services (bullets, each ≤20 words): Extract from technical narrative
   - Data Model Changes (table): Extract schemas, fields
   - API Changes (table): Extract endpoints
   - Env/Config (table): Extract environment variables

5. **Execution Plan & Issues:**
   - Implementation Plan (≤60 words each phase): Extract from technical narrative
   - Risks & Mitigations (table): Technical risks only

6. **Issue Breakdown (Section 8) - CRITICAL:**
   - Extract implementation tasks from narrative
   - For each issue:
     * Overview (≤50 words) → maps to enhancement.template.md
     * Accepts (≤5 bullets, ≤12 words) → maps to enhancement.template.md
     * Tech Approach (≤6 bullets) → maps to enhancement.template.md
     * Files/Components: List files to modify
     * Dependencies: Issue numbers (#N, #M) or "None"
     * Classification: 1-10 scale (infer from complexity)
     * Size/Complexity: S/M/L (infer from scope)

**Validate Spec:**
- [ ] All length limits respected
- [ ] PRD → Spec mapping matches PRD section 9
- [ ] Issue breakdowns have all 7 required fields
- [ ] Dependencies are explicit or "None"
- [ ] Classifications are 1-10 scale
- [ ] References BRD for constraints (pricing, metrics)
- [ ] References PRD for requirements

**Write Spec:**
- Output to: `memory-bank/requirements/specs/[feature-id]-spec.md`
- Update `related_spec` in BRD and PRD to point to this Spec
- Display: "✅ Spec created: memory-bank/requirements/specs/[feature-id]-spec.md"

### 6. UPDATE CROSS-REFERENCES

**After all three docs generated:**

1. **Update BRD frontmatter:**
   ```yaml
   related_prd: ../prds/[feature-id]-prd.md
   ```

2. **Update PRD frontmatter:**
   ```yaml
   related_spec: ../specs/[feature-id]-spec.md
   ```

3. **Verify all cross-references are valid:**
   - BRD → PRD
   - PRD → Spec
   - PRD references BRD sections
   - Spec references BRD and PRD sections

### 7. COMPLETION SUMMARY

**Display final summary:**
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Release Documentation Complete: [Feature Name]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Source: memory-bank/requirements/source-docs/[subfolder]/ (3 files, ~2380 lines)

Generated Documents:

📊 BRD (Business Requirements):
   memory-bank/requirements/brds/[feature-id]-brd.md
   - 5 business goals
   - 3 pricing tiers
   - 6 metrics across 3 categories
   
📝 PRD (Product Requirements):
   memory-bank/requirements/prds/[feature-id]-prd.md
   - 6 functional requirements (R1-R6)
   - 4 user stories
   - 5-step user journey
   - References: BRD (3 sections)
   
⚙️ Spec (Technical Specification):
   memory-bank/requirements/specs/[feature-id]-spec.md
   - 8 implementation issues
   - Complete architecture design
   - Issue breakdown ready for /scope-release
   - References: BRD (2 sections), PRD (6 requirements)

Next Steps:
1. Review generated documents for accuracy
2. Fill any remaining {{PLACEHOLDERS}} if needed
3. Run /scope-release to create GitHub issues from spec
4. Run /guide-release to populate current-release.md

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

---

## AGGREGATION STRATEGY

**When reading multiple narrative files:**

1. **Business Context (for BRD):**
   - Aggregate all business goals across files
   - Merge market/segment mentions
   - Consolidate pricing/revenue information
   - Prioritize explicit over implied

2. **Product Requirements (for PRD):**
   - Extract user goals from PRD-focused narratives
   - Extract functional requirements from all files
   - User stories from use cases mentioned
   - Problem statements from motivation sections

3. **Technical Details (for Spec):**
   - Extract architecture from technical narratives
   - Extract implementation tasks from specs
   - Data models from schema mentions
   - API endpoints from technical details

**Conflict Resolution:**
- If multiple files have conflicting info: Prioritize most recent/detailed
- If files focus on different aspects: Merge complementary information
- If info is duplicated: Use once, reference the canonical source

---

## SMART DEFAULTS

**If source material is incomplete:**

**Missing Business Context:**
- Infer target segments from user goals mentioned
- Create reasonable pricing tiers (Free, Starter, Enterprise)
- Synthesize GTM roadmap from implementation phases

**Missing Product Requirements:**
- Extract functional requirements from technical details (reverse engineer)
- Create user stories from use cases or technical features
- Synthesize user journey from implementation flow

**Missing Technical Details:**
- Infer architecture from functional requirements
- Create reasonable issue breakdown from requirements
- Estimate classifications based on requirement complexity

**Always validate with user:**
```
⚠️ Note: Some sections synthesized from available material:
- Pricing tiers (not explicitly in source)
- User journey (derived from technical flow)

Review generated docs carefully.
```

---

## ERROR HANDLING

**If source folder not found:**
```
❌ Error: Folder 'memory-bank/requirements/source-docs/[subfolder]/' not found

Available folders:
- submodule-isolation/
- classification/
- monetization/

Use: /create-release-docs [folder-name]
```

**If no .md files in folder:**
```
❌ Error: No markdown files found in 'memory-bank/requirements/source-docs/[subfolder]/'

Please add source material to this folder first.
```

**If validation fails:**
```
⚠️ Warning: [Document] validation issue:
- Field exceeds length limit: [field] (actual: 60 words, max: 40)

Truncating and continuing...
```

**If cross-reference fails:**
```
⚠️ Warning: Could not update cross-reference in [file]

Please manually verify related_prd and related_spec fields.
```

---

## COST OPTIMIZATION

**Sequential generation with context carryover:**
- BRD generation: Read all narratives once
- PRD generation: Read BRD + narratives (BRD provides context, reduces narrative parsing)
- Spec generation: Read BRD + PRD + narratives (BRD+PRD provide context, reduces narrative parsing)

**Expected token usage:**
- Single pass: ~60-70% of running 3 separate commands
- Cross-referencing eliminates duplication
- Aggregated narrative reading (once, not 3 times)

---

## GUARDRAILS

1. **Sequential Dependencies:**
   - MUST generate BRD before PRD (PRD references BRD)
   - MUST generate PRD before Spec (Spec references BRD + PRD)
   - If any step fails, stop and report error

2. **Validation at Each Step:**
   - Validate BRD before proceeding to PRD
   - Validate PRD before proceeding to Spec
   - If validation fails: Display warnings but continue (truncate/fix)

3. **Cross-Reference Integrity:**
   - After all docs generated, verify all references
   - Check BRD → PRD link
   - Check PRD → Spec link
   - Check PRD references to BRD sections
   - Check Spec references to BRD + PRD sections

4. **User Confirmation:**
   - After folder selection, confirm before proceeding
   - After discovering files, display count and confirm
   - After all docs generated, display summary

---

**Behavior:**
- If invoked with subfolder name (e.g., `/create-release-docs submodule-isolation`), use that folder
- If no subfolder provided, list folders in `memory-bank/requirements/source-docs/` and prompt for selection
- Always aggregate all .md files in the selected folder
- Generate BRD → PRD → Spec sequentially
- Update cross-references after all docs generated
- Display completion summary with next steps