claude-code-templates 1.21.4 → 1.21.6

package/components/commands/documentation/migration-guide.md

@@ -0,0 +1,250 @@
+---
+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
+model: sonnet
+---
+
+# 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:**
+   ```markdown
+   ## 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:**
+   ```markdown
+   ### Removed: `oldMethod()`
+   **Before:**
+   ```javascript
+   const result = library.oldMethod(param1, param2);
+   ```
+   
+   **After:**
+   ```javascript
+   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**
+    
+    ```markdown
+    ## 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**
+    - Identify potential migration risks
+    - Create contingency plans for each risk
+    - Document escalation procedures
+    - Plan for extended timeline scenarios
+    - Prepare communication for stakeholders
+
+18. **Post-Migration Tasks**
+    - Clean up deprecated code and configurations
+    - Update documentation and README files
+    - Review and optimize new implementation
+    - Conduct post-migration retrospective
+    - Plan for future maintenance and updates
+
+19. **Validation and Testing**
+    - Create comprehensive test plans
+    - Document acceptance criteria
+    - Set up automated regression testing
+    - Plan user acceptance testing
+    - Implement monitoring and alerting
+
+20. **Documentation Updates**
+    - Update API documentation
+    - Revise development guides
+    - Update deployment documentation
+    - Create troubleshooting guides
+    - Update team onboarding materials
+
+**Migration Types and Specific Considerations:**
+
+**Framework Migration (React 17 → 18):**
+- Update React and ReactDOM imports
+- Replace deprecated lifecycle methods
+- Update testing library methods
+- Handle concurrent features and Suspense
+
+**Database Migration (MySQL → PostgreSQL):**
+- Convert SQL syntax differences
+- Update data types and constraints
+- Migrate stored procedures to functions
+- Update ORM configurations
+
+**Cloud Migration (On-premise → AWS):**
+- Containerize applications
+- Update CI/CD pipelines
+- Configure cloud services
+- Implement infrastructure as code
+
+**Architecture Migration (Monolith → Microservices):**
+- Identify service boundaries
+- Implement inter-service communication
+- Set up service discovery
+- Plan data consistency strategies
+
+Remember to:
+- Test thoroughly in non-production environments first
+- Communicate progress and issues regularly
+- Document lessons learned for future migrations
+- Keep the migration guide updated based on real experiences

package/components/commands/documentation/troubleshooting-guide.md

@@ -0,0 +1,370 @@
+---
+allowed-tools: Read, Write, Edit, Bash
+argument-hint: [system-component] | --application | --database | --network | --deployment | --comprehensive
+description: Generate systematic troubleshooting documentation with diagnostic procedures, common issues, and automated solutions
+model: sonnet
+---
+
+# Troubleshooting Guide Generator
+
+Generate troubleshooting documentation: $ARGUMENTS
+
+## Current System Context
+
+- System architecture: @docker-compose.yml or @k8s/ or detect deployment type
+- Log locations: !`find . -name "*log*" -type d | head -3`
+- Monitoring setup: !`grep -r "prometheus\|grafana\|datadog" . 2>/dev/null | wc -l` monitoring references
+- Error patterns: !`find . -name "*.log" | head -3` recent logs
+- Health endpoints: !`grep -r "health\|status" src/ 2>/dev/null | head -3`
+
+## Task
+
+Create comprehensive troubleshooting guide with systematic diagnostic procedures: $ARGUMENTS
+
+1. **System Overview and Architecture**
+   - Document the system architecture and components
+   - Map out dependencies and integrations
+   - Identify critical paths and failure points
+   - Create system topology diagrams
+   - Document data flow and communication patterns
+
+2. **Common Issues Identification**
+   - Collect historical support tickets and issues
+   - Interview team members about frequent problems
+   - Analyze error logs and monitoring data
+   - Review user feedback and complaints
+   - Identify patterns in system failures
+
+3. **Troubleshooting Framework**
+   - Establish systematic diagnostic procedures
+   - Create problem isolation methodologies
+   - Document escalation paths and procedures
+   - Set up logging and monitoring checkpoints
+   - Define severity levels and response times
+
+4. **Diagnostic Tools and Commands**
+   
+   ```markdown
+   ## Essential Diagnostic Commands
+   
+   ### System Health
+   ```bash
+   # Check system resources
+   top                    # CPU and memory usage
+   df -h                 # Disk space
+   free -m               # Memory usage
+   netstat -tuln         # Network connections
+   
+   # Application logs
+   tail -f /var/log/app.log
+   journalctl -u service-name -f
+   
+   # Database connectivity
+   mysql -u user -p -e "SELECT 1"
+   psql -h host -U user -d db -c "SELECT 1"
+   ```
+   ```
+
+5. **Issue Categories and Solutions**
+
+   **Performance Issues:**
+   ```markdown
+   ### Slow Response Times
+   
+   **Symptoms:**
+   - API responses > 5 seconds
+   - User interface freezing
+   - Database timeouts
+   
+   **Diagnostic Steps:**
+   1. Check system resources (CPU, memory, disk)
+   2. Review application logs for errors
+   3. Analyze database query performance
+   4. Check network connectivity and latency
+   
+   **Common Causes:**
+   - Database connection pool exhaustion
+   - Inefficient database queries
+   - Memory leaks in application
+   - Network bandwidth limitations
+   
+   **Solutions:**
+   - Restart application services
+   - Optimize database queries
+   - Increase connection pool size
+   - Scale infrastructure resources
+   ```
+
+6. **Error Code Documentation**
+   
+   ```markdown
+   ## Error Code Reference
+   
+   ### HTTP Status Codes
+   - **500 Internal Server Error**
+     - Check application logs for stack traces
+     - Verify database connectivity
+     - Check environment variables
+   
+   - **404 Not Found**
+     - Verify URL routing configuration
+     - Check if resources exist
+     - Review API endpoint documentation
+   
+   - **503 Service Unavailable**
+     - Check service health status
+     - Verify load balancer configuration
+     - Check for maintenance mode
+   ```
+
+7. **Environment-Specific Issues**
+   - Document development environment problems
+   - Address staging/testing environment issues
+   - Cover production-specific troubleshooting
+   - Include local development setup problems
+
+8. **Database Troubleshooting**
+   
+   ```markdown
+   ### Database Connection Issues
+   
+   **Symptoms:**
+   - "Connection refused" errors
+   - "Too many connections" errors
+   - Slow query performance
+   
+   **Diagnostic Commands:**
+   ```sql
+   -- Check active connections
+   SHOW PROCESSLIST;
+   
+   -- Check database size
+   SELECT table_schema, 
+          ROUND(SUM(data_length + index_length) / 1024 / 1024, 1) AS 'DB Size in MB' 
+   FROM information_schema.tables 
+   GROUP BY table_schema;
+   
+   -- Check slow queries
+   SHOW VARIABLES LIKE 'slow_query_log';
+   ```
+   ```
+
+9. **Network and Connectivity Issues**
+   
+   ```markdown
+   ### Network Troubleshooting
+   
+   **Basic Connectivity:**
+   ```bash
+   # Test basic connectivity
+   ping example.com
+   telnet host port
+   curl -v https://api.example.com/health
+   
+   # DNS resolution
+   nslookup example.com
+   dig example.com
+   
+   # Network routing
+   traceroute example.com
+   ```
+   
+   **SSL/TLS Issues:**
+   ```bash
+   # Check SSL certificate
+   openssl s_client -connect example.com:443
+   curl -vI https://example.com
+   ```
+   ```
+
+10. **Application-Specific Troubleshooting**
+    
+    **Memory Issues:**
+    ```markdown
+    ### Out of Memory Errors
+    
+    **Java Applications:**
+    ```bash
+    # Check heap usage
+    jstat -gc [PID]
+    jmap -dump:format=b,file=heapdump.hprof [PID]
+    
+    # Analyze heap dump
+    jhat heapdump.hprof
+    ```
+    
+    **Node.js Applications:**
+    ```bash
+    # Monitor memory usage
+    node --inspect app.js
+    # Use Chrome DevTools for memory profiling
+    ```
+    ```
+
+11. **Security and Authentication Issues**
+    
+    ```markdown
+    ### Authentication Failures
+    
+    **Symptoms:**
+    - 401 Unauthorized responses
+    - Token validation errors
+    - Session timeout issues
+    
+    **Diagnostic Steps:**
+    1. Verify credentials and tokens
+    2. Check token expiration
+    3. Validate authentication service
+    4. Review CORS configuration
+    
+    **Common Solutions:**
+    - Refresh authentication tokens
+    - Clear browser cookies/cache
+    - Verify CORS headers
+    - Check API key permissions
+    ```
+
+12. **Deployment and Configuration Issues**
+    
+    ```markdown
+    ### Deployment Failures
+    
+    **Container Issues:**
+    ```bash
+    # Check container status
+    docker ps -a
+    docker logs container-name
+    
+    # Check resource limits
+    docker stats
+    
+    # Debug container
+    docker exec -it container-name /bin/bash
+    ```
+    
+    **Kubernetes Issues:**
+    ```bash
+    # Check pod status
+    kubectl get pods
+    kubectl describe pod pod-name
+    kubectl logs pod-name
+    
+    # Check service connectivity
+    kubectl get svc
+    kubectl port-forward pod-name 8080:8080
+    ```
+    ```
+
+13. **Monitoring and Alerting Setup**
+    - Configure health checks and monitoring
+    - Set up log aggregation and analysis
+    - Implement alerting for critical issues
+    - Create dashboards for system metrics
+    - Document monitoring thresholds
+
+14. **Escalation Procedures**
+    
+    ```markdown
+    ## Escalation Matrix
+    
+    ### Severity Levels
+    
+    **Critical (P1):** System down, data loss
+    - Immediate response required
+    - Escalate to on-call engineer
+    - Notify management within 30 minutes
+    
+    **High (P2):** Major functionality impaired
+    - Response within 2 hours
+    - Escalate to senior engineer
+    - Provide hourly updates
+    
+    **Medium (P3):** Minor functionality issues
+    - Response within 8 hours
+    - Assign to appropriate team member
+    - Provide daily updates
+    ```
+
+15. **Recovery Procedures**
+    - Document system recovery steps
+    - Create data backup and restore procedures
+    - Establish rollback procedures for deployments
+    - Document disaster recovery processes
+    - Test recovery procedures regularly
+
+16. **Preventive Measures**
+    - Implement monitoring and alerting
+    - Set up automated health checks
+    - Create deployment validation procedures
+    - Establish code review processes
+    - Document maintenance procedures
+
+17. **Knowledge Base Integration**
+    - Link to relevant documentation
+    - Reference API documentation
+    - Include links to monitoring dashboards
+    - Connect to team communication channels
+    - Integrate with ticketing systems
+
+18. **Team Communication**
+    
+    ```markdown
+    ## Communication Channels
+    
+    ### Immediate Response
+    - Slack: #incidents channel
+    - Phone: On-call rotation
+    - Email: alerts@company.com
+    
+    ### Status Updates
+    - Status page: status.company.com
+    - Twitter: @company_status
+    - Internal wiki: troubleshooting section
+    ```
+
+19. **Documentation Maintenance**
+    - Regular review and updates
+    - Version control for troubleshooting guides
+    - Feedback collection from users
+    - Integration with incident post-mortems
+    - Continuous improvement processes
+
+20. **Self-Service Tools**
+    - Create diagnostic scripts and tools
+    - Build automated recovery procedures
+    - Implement self-healing systems
+    - Provide user-friendly diagnostic interfaces
+    - Create chatbot integration for common issues
+
+**Advanced Troubleshooting Techniques:**
+
+**Log Analysis:**
+```bash
+# Search for specific errors
+grep -i "error" /var/log/app.log | tail -50
+
+# Analyze log patterns
+awk '{print $1}' access.log | sort | uniq -c | sort -nr
+
+# Monitor logs in real-time
+tail -f /var/log/app.log | grep -i "exception"
+```
+
+**Performance Profiling:**
+```bash
+# System performance
+iostat -x 1
+sar -u 1 10
+vmstat 1 10
+
+# Application profiling
+strace -p [PID]
+perf record -p [PID]
+```
+
+Remember to:
+- Keep troubleshooting guides up-to-date
+- Test all documented procedures regularly
+- Collect feedback from users and improve guides
+- Include screenshots and visual aids where helpful
+- Make guides searchable and well-organized