BMAD-METHOD/.bmad-core/tasks/doc-migration-task.md

Document Migration Task (V3 to V4)

Purpose

Migrate BMAD-METHOD V3 documents to V4 format by aligning section headings, structure, and content organization with V4 templates while preserving all user-generated content.

When to Use This Task

[[LLM: This task should be used after a V3 to V4 upgrade when the user has existing PRD and Architecture documents that need to be aligned with V4 templates. The task handles:

• PRD migration to V4 format
• Architecture migration (single backend or full-stack)
• Merging separate front-end and backend architecture docs into full-stack-architecture.md ]]

Use this task when:

• You've upgraded from BMAD V3 to V4
• Your documents have V3 section headings that differ from V4
• You have separate front-end and backend architecture documents
• You need to align your documents with V4 agent expectations

Prerequisites

• Completed V3 to V4 upgrade
• Documents located in docs/ folder
• Access to V4 templates in .bmad-core/templates/

Process

1. Analyze Existing Documents

[[LLM: First, examine what documents exist in the docs/ folder:

• Look for prd.md or similar
• Look for architecture.md or similar
• Check for front-end-architecture.md or similar
• Note which documents need migration ]]

Identify which documents need migration:

• PRD document
• Architecture document(s)
• Any front-end specific architecture

2. PRD Migration

[[LLM: When migrating the PRD:

1. Read the existing PRD content
2. Compare with .bmad-core/templates/prd-tmpl.md
3. Map V3 sections to V4 sections:
   • Keep all user content
   • Update section headings to match V4
   • Add any missing V4 sections with placeholder content
   • Preserve any custom sections at the end

V3 → V4 Common Mappings:

• "Executive Summary" → "Goals and Background Context"
• "Goals" → "Goals and Background Context > Goals"
• "Requirements" → Keep as is
• "User Stories" → "Epics and User Stories" ]]

PRD Section Mapping:

1. Update main heading structure to match V4 template
2. Preserve all existing content under new headings
3. Add missing sections with appropriate prompts for completion
4. Maintain any project-specific custom sections

3. Architecture Migration

[[LLM: Determine architecture migration path:

1. If ONLY backend architecture exists:
   • Use .bmad-core/templates/architecture-tmpl.md
   • Map sections appropriately
2. If BOTH backend AND front-end architecture exist:
   • Use .bmad-core/templates/full-stack-architecture-tmpl.md
   • Merge content from both documents
   • Create unified architecture document
3. Section mapping approach:
   • Preserve all technical decisions and content
   • Update headings to match V4 structure
   • Combine overlapping sections intelligently ]]

Architecture Migration Paths:

Single Architecture → architecture.md

• Update section headings to V4 format
• Add any missing V4 sections
• Preserve all technical content

Multiple Architecture Files → full-stack-architecture.md

• Merge backend and front-end content
• Organize under V4 full-stack sections
• Eliminate redundancy while preserving all unique content
• Create unified system view

4. Content Preservation Rules

[[LLM: CRITICAL preservation rules:

1. NEVER delete user content
2. If unsure where content belongs, add it to the most relevant section
3. Preserve all:
   • Technical decisions
   • Diagrams and code blocks
   • Lists and tables
   • Custom sections
   • Links and references
4. Add LLM: migration note comments where manual review might be needed ]]

Always Preserve:

• All user-written content
• Technical specifications
• Diagrams (Mermaid, ASCII, etc.)
• Code examples
• Custom sections not in V4 template

5. Create Migration Report

[[LLM: After migration, create a brief report:

• List all documents migrated
• Note any sections that need manual review
• Highlight any content that was moved significantly
• Suggest next steps ]]

Generate migration-report.md with:

• Documents migrated
• Section mappings performed
• Any content requiring review
• Recommendations for manual updates

Validation Checklist

Before completing migration:

• All original content is preserved
• Section headings match V4 templates
• No duplicate content in merged documents
• Documents are properly formatted
• Any uncertain mappings are marked for review

Example Migrations

V3 PRD Section → V4 PRD Section

V3: ## Executive Summary     → V4: ## Goals and Background Context
V3: ## Goals                 → V4: ### Goals
V3: ## Success Metrics       → V4: ## Success Metrics and KPIs

Architecture Merge Example

backend-architecture.md + front-end-architecture.md → full-stack-architecture.md

V3 Backend: ## Technology Stack    →  V4: ## Technology Stack > ### Backend
V3 Frontend: ## UI Architecture    →  V4: ## Technology Stack > ### Frontend

Post-Migration Steps

1. Review migrated documents for accuracy
2. Fill in any placeholder sections added
3. Run document sharding if needed
4. Update any cross-references between documents

Important Notes

• This task requires careful analysis of existing content
• When in doubt, preserve content and mark for review
• The goal is structure alignment, not content rewriting
• Custom sections should be retained even if not in V4 template
• MOST CRITICAL - The ONLY LEVEL 2 HEADINGS should be what are in the V4 templates. so content preservation might mean making some content that was level 2 a level 3 now. UNDERSTAND that the LEVEL 2 headings result in file names