/migration-guide

allowed-tools: Read, Write, Edit, Bash
argument-hint: [migration-type] | framework | database | cloud | architecture | --version-upgrade
description: Create comprehensive migration guides with step-by-step procedures, validation, and rollback strategies

Migration Guide Generator

Create comprehensive migration guide: $ARGUMENTS

Current System Analysis

• Current versions: @package.json or @requirements.txt or detect from lock files
• Migration history: !`find . -name "*migration*" -o -name "*upgrade*" | head -5`
• Database schema: !`find . -name "*schema*" -o -name "*.sql" | head -3`
• Dependencies: !`grep -c "dependency\|require\|import" package.json requirements.txt 2>/dev/null || echo "0"`
• Infrastructure: @docker-compose.yml or @k8s/ or @terraform/ (if exists)

Task

Generate systematic migration guide with comprehensive safety measures: $ARGUMENTS

1. **Migration Scope Analysis**

• Identify what is being migrated (framework, library, architecture, etc.)
• Determine source and target versions or technologies
• Assess the scale and complexity of the migration
• Identify affected systems and components

2. **Impact Assessment**

• Analyze breaking changes between versions
• Identify deprecated features and APIs
• Review new features and capabilities
• Assess compatibility requirements and constraints
• Evaluate performance and security implications

3. **Prerequisites and Requirements**

• Document system requirements for the target version
• List required tools and dependencies
• Specify minimum versions and compatibility requirements
• Identify necessary skills and team preparation
• Outline infrastructure and environment needs

4. **Pre-Migration Preparation**

• Create comprehensive backup strategies
• Set up development and testing environments
• Document current system state and configurations
• Establish rollback procedures and contingency plans
• Create migration timeline and milestones

5. **Step-by-Step Migration Process**

**Example for Framework Upgrade:**

   ## Step 1: Environment Setup
   1. Update development environment
   2. Install new framework version
   3. Update build tools and dependencies
   4. Configure IDE and tooling
   
   ## Step 2: Dependencies Update
   1. Update package.json/requirements.txt
   2. Resolve dependency conflicts
   3. Update related libraries
   4. Test compatibility
   
   ## Step 3: Code Migration
   1. Update import statements
   2. Replace deprecated APIs
   3. Update configuration files
   4. Modify build scripts

6. **Breaking Changes Documentation**

• List all breaking changes with examples
• Provide before/after code comparisons
• Explain the rationale behind changes
• Offer alternative approaches for removed features

**Example Breaking Change:**

   ### Removed: `oldMethod()`
   **Before:**
   ```javascript
   const result = library.oldMethod(param1, param2);

**After:**

   const result = library.newMethod({ 
     param1: param1, 
     param2: param2 
   });

**Rationale:** Improved type safety and extensibility

7. **Configuration Changes**
   - Document configuration file updates
   - Explain new configuration options
   - Provide configuration migration scripts
   - Show environment-specific configurations

8. **Database Migration (if applicable)**
   - Create database schema migration scripts
   - Document data transformation requirements
   - Provide backup and restore procedures
   - Test migration with sample data
   - Plan for zero-downtime migrations

9. **Testing Strategy**
   - Update existing tests for new APIs
   - Create migration-specific test cases
   - Implement integration and E2E tests
   - Set up performance and load testing
   - Document test scenarios and expected outcomes

10. **Performance Considerations**
    - Document performance changes and optimizations
    - Provide benchmarking guidelines
    - Identify potential performance regressions
    - Suggest monitoring and alerting updates
    - Include memory and resource usage changes

11. **Security Updates**
    - Document security improvements and changes
    - Update authentication and authorization code
    - Review and update security configurations
    - Update dependency security scanning
    - Document new security best practices

12. **Deployment Strategy**
    - Plan phased rollout approach
    - Create deployment scripts and automation
    - Set up monitoring and health checks
    - Plan for blue-green or canary deployments
    - Document rollback procedures

13. **Common Issues and Troubleshooting**
    
    ```markdown
    ## Common Migration Issues
    
    ### Issue: Import/Module Resolution Errors
    **Symptoms:** Cannot resolve module 'old-package'
    **Solution:** 
    1. Update import statements to new package names
    2. Check package.json for correct dependencies
    3. Clear node_modules and reinstall
    
    ### Issue: API Method Not Found
    **Symptoms:** TypeError: oldMethod is not a function
    **Solution:** Replace with new API as documented in step 3

14. **Team Communication and Training**

• Create team training materials
• Schedule knowledge sharing sessions
• Document new development workflows
• Update coding standards and guidelines
• Create quick reference guides

15. **Tools and Automation**

• Provide migration scripts and utilities
• Create code transformation tools (codemods)
• Set up automated compatibility checks
• Implement CI/CD pipeline updates
• Create validation and verification tools

16. **Timeline and Milestones**

    ## Migration Timeline
    
    ### Phase 1: Preparation (Week 1-2)
    - [ ] Environment setup
    - [ ] Team training
    - [ ] Development environment migration
    
    ### Phase 2: Development (Week 3-6)
    - [ ] Core application migration