/migration-guide

Create migration guides for updates

qdhenry@qdhenry

GitHub

From plugin

claude-command-suite

1.3k199 skills89 agents199 commands

Install

$ npx -y skills add qdhenry/Claude-Command-Suite --agent claude-code

How it fires

How this command gets triggered: by you, by Claude, or both.

Fires itselfClaude auto-loads it when your prompt matches the work.
You can call itInvoke it directly when you want it.
Slash command/migration-guide

Context preview

What this command does when you run it.

Create migration guides for updates

Command definition

migration-guide.md

Migration Guide Generator Command

Create migration guides for updates

Instructions

Follow this systematic approach to create migration guides: **$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
    - [ ] Testing and validation
    - [ ] Performance optimization
    
    ### Phase 3: Deployment (Week 7-8)
    - [ ] Staging deployment
    - [ ] Production deployment
    - [ ] Monitoring and support

17. **Risk Mitigation**