# 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