ros/BMAD-METHOD
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

prd migration works well enough

Browse Source
This commit is contained in:
Brian Madison
2025-06-15 00:02:17 -05:00
parent 8b60410f7a
commit 193ed8f11f
1 changed files with 85 additions and 164 deletions
Download Patch File Download Diff File Expand all files Collapse all files

249
.bmad-core/tasks/doc-migration-task.md
View File

@@ -2,197 +2,118 @@
## Purpose
Migrate BMAD-METHOD documents to match V4 template structure exactly, preserving all content while enforcing strict template compliance.
Simple document migration that cleans up heading formats and adds epic structure for PRDs.
## Task Requirements
1. **Input**: User MUST specify the document to migrate (e.g., `docs/prd.md`)
2. **Template**: User MUST specify the V4 template to use (e.g., `.bmad-core/templates/prd-tmpl.md`)
3. **Validation**: Verify document and template are compatible types
4. **Output**: Creates migrated document with original name, backs up original with `.bak` extension
[[LLM: VALIDATION REQUIREMENTS:
- Both input document and template paths MUST be provided by the user
- Do NOT assume or select templates automatically
- Validate that document type matches template type (e.g., PRD → PRD template)
- Reject incompatible migrations (e.g., PRD → architecture template)
]]
1. **Input**: User specifies the document to migrate (e.g., `docs/prd.md`)
2. **Detection**: Automatically determine if it's a PRD or other document type
3. **Migration**: Apply appropriate transformations
4. **Backup**: Create backup with `.bak` extension
## Migration Rules
### Strict Template Compliance
### For PRDs
- Find all level 3 headings that appear to be epics
- Add a level 2 heading "## Epic #" (incrementing number) before each epic
- Also apply the heading cleanup rules below
[[LLM: CRITICAL RULES:
### For All Documents
- Find all level 2 headings (`## ...`)
- Remove leading numbers and symbols
- Keep only alphabetic characters and spaces
- Examples:
- `## 1. Foo & Bar` → `## Foo Bar`
- `## 2.1 Technical Overview` → `## Technical Overview`
- `## 3) User Experience` → `## User Experience`
1. The ONLY Level 2 headings (##) allowed are EXACTLY those in the V4 template
2. No additions, no removals, no modifications to Level 2 headings
3. All user content must be preserved and placed under appropriate template sections
4. Remove any existing table of contents
5. Never delete user content - find the most appropriate section
6. DO NOT add any LLM prompts, placeholders, or "TBD" content
7. Leave empty sections empty - no instructions or guidance text
## Detection Logic
]]
A document is considered a PRD if:
- Filename contains "prd" (case insensitive)
- OR main title contains "Product Requirements" or "PRD"
- OR contains sections like "User Stories", "Functional Requirements", "Acceptance Criteria"
### Content Migration Process
## Implementation Steps
1. **Read Template Structure**
1. **Backup Original**: Copy `filename.md` to `filename.md.bak`
2. **Detect Type**: Check if document is a PRD
3. **Process Headings**:
- Clean all level 2 headings
- If PRD: Add epic structure before level 3 headings that look like epics
4. **Write Result**: Overwrite original file with migrated content
- Extract all Level 2 headings from the V4 template
- These are the ONLY Level 2 headings allowed in the final document
## Epic Detection for PRDs
2. **Analyze Original Document**
Level 3 headings are treated as epics if they:
- Describe features or functionality
- Are substantial sections (not just "Overview" or "Notes")
- Common epic patterns: "User Management", "Payment Processing", "Reporting Dashboard"
- Identify all content blocks
- Note original section organization
- Flag any custom sections
The epic numbering starts at 1 and increments for each epic found.
3. **Create Backup First**
- Rename original file: `mv filename.md filename.md.bak`
- This preserves the original completely
4. **Create New File**
- Create new `filename.md` from scratch
- Start with template structure (all Level 2 headings)
- For each content block from original:
- Find the most appropriate V4 template section
- If original had Level 2 heading not in template, demote to Level 3
- Preserve all text, lists, code blocks, diagrams, tables
- Remove only table of contents sections
- **IMPORTANT**: Do NOT add any LLM prompts, placeholders, or instructions
- If a template section has no matching content, leave it empty
5. **Validate Content Preservation**
- For each major content block from original (excluding headings):
- Use grep or search to verify it exists in new file
- Report any content that couldn't be verified
- This ensures no accidental content loss
## Example Migration
## Example
### Before (PRD):
```markdown
Original (prd.md):
# Product Requirements Document
## 1. Executive Summary
Content here...
## 2.1 Functional Requirements & Specs
Content here...
### User Management System
Epic content...
### Payment Processing
Epic content...
## 3) Success Metrics
Content here...
```text
### After (PRD):
```markdown
# Product Requirements Document
## Executive Summary
Content here...
[content...]
## Functional Requirements Specs
Content here...
## Custom Feature Section
## Epic 1
### User Management System
Epic content...
[content...]
## Epic 2
### Payment Processing
Epic content...
## Table of Contents
[toc...]
Template (prd-tmpl.md):
## Goals and Background Context
## Functional Requirements
## Success Metrics and KPIs
Result (prd.md):
## Goals and Background Context
[executive summary content moved here]
### Custom Feature Section
[content preserved but demoted to Level 3]
## Functional Requirements
## Success Metrics and KPIs
## Success Metrics
Content here...
```
## Execution Instructions
### Before (Non-PRD):
```markdown
# Architecture Document
[[LLM: When executing this task:
## 1. System Overview
Content...
1. Ask user for BOTH: input file path AND template path (do not assume)
2. Validate compatibility:
- Check document title/type (PRD, Architecture, etc.)
- Ensure template matches document type
- REJECT if types don't match (e.g., "Cannot migrate PRD to architecture template")
3. Read both files completely
4. Rename original to .bak: `mv original.md original.md.bak`
5. Extract Level 2 headings from template - these are MANDATORY
6. Create NEW file with original name
7. Build new content:
- Start with all template Level 2 sections
- Map original content to appropriate sections
- Demote any non-template Level 2 headings to Level 3
- Leave empty sections empty (no placeholders or instructions)
8. Validate content preservation:
- Extract key content snippets from .bak file
- Use grep to verify each exists in new file
- Report any missing content
9. Report migration summary:
- Sections moved/demoted
- Content validation results
- Any manual review needed
## 2.1 Technical Stack & Tools
Content...
```text
]]
### After (Non-PRD):
```markdown
# Architecture Document
### Document Type Detection
## System Overview
Content...
[[LLM: Detect document type by examining:
- File name (prd.md, architecture.md, etc.)
- Main title (# Product Requirements Document, # Architecture, etc.)
- Content patterns (user stories → PRD, technology stack → Architecture)
Template compatibility:
- prd-tmpl.md → Only for PRD documents
- architecture-tmpl.md → Only for backend/single architecture
- full-stack-architecture-tmpl.md → Only for architecture documents (can merge multiple)
]]
## Common Migrations
Valid migrations:
- `prd.md` → `.bmad-core/templates/prd-tmpl.md`
- `architecture.md` → `.bmad-core/templates/architecture-tmpl.md`
- `architecture.md` + `front-end-architecture.md` → `.bmad-core/templates/full-stack-architecture-tmpl.md`
Invalid migrations (MUST REJECT):
- `prd.md` → `.bmad-core/templates/architecture-tmpl.md`
- `architecture.md` → `.bmad-core/templates/prd-tmpl.md`
- `ux-ui-spec.md` → `.bmad-core/templates/prd-tmpl.md`
## Validation
After migration verify:
- [ ] All Level 2 headings match template exactly
- [ ] All original content is preserved (use grep validation)
- [ ] No table of contents remains
- [ ] Backup file exists with .bak extension
- [ ] Custom sections demoted to Level 3 or lower
### Content Validation Example
[[LLM: Example validation approach:
1. Extract significant text blocks from .bak file (>20 words)
2. For each block, grep in new file:
```bash
grep -F "first 10-15 words of content block" newfile.md
```
3. Track validation results:
- ✓ Found: content successfully migrated
- ✗ Missing: needs investigation
4. Report any content that couldn't be found
]]
## Technical Stack Tools
Content...
```