chore: import upstream snapshot with attribution

cli-tool/components/commands/utilities/code-permutation-tester.md

@@ -0,0 +1,341 @@
+# Code Permutation Tester
+
+Test multiple code variations through simulation before implementation with quality gates and performance prediction.
+
+## Instructions
+
+You are tasked with systematically testing multiple code implementation approaches through simulation to optimize decisions before actual development. Follow this approach: **$ARGUMENTS**
+
+### 1. Prerequisites Assessment
+
+**Critical Code Context Validation:**
+
+- **Code Scope**: What specific code area/function/feature are you testing variations for?
+- **Variation Types**: What different approaches are you considering?
+- **Quality Criteria**: How will you evaluate which variation is best?
+- **Constraints**: What technical, performance, or resource constraints apply?
+- **Decision Timeline**: When do you need to choose an implementation approach?
+
+**If context is unclear, guide systematically:**
+
+```
+Missing Code Scope:
+"What specific code area needs permutation testing?
+- Algorithm Implementation: Different algorithmic approaches for the same problem
+- Architecture Pattern: Various structural patterns (MVC, microservices, etc.)
+- Performance Optimization: Multiple optimization strategies for bottlenecks
+- API Design: Different interface design approaches
+- Data Structure Choice: Various data organization strategies
+
+Please specify the exact function, module, or system component."
+
+Missing Variation Types:
+"What different implementation approaches are you considering?
+- Algorithmic Variations: Different algorithms solving the same problem
+- Framework/Library Choices: Various tech stack options
+- Design Pattern Applications: Different structural and behavioral patterns
+- Performance Trade-offs: Speed vs. memory vs. maintainability variations
+- Integration Approaches: Different ways to connect with existing systems"
+```
+
+### 2. Code Variation Generation
+
+**Systematically identify and structure implementation alternatives:**
+
+#### Implementation Approach Matrix
+```
+Code Variation Framework:
+
+Algorithmic Variations:
+- Brute Force: Simple, readable implementation
+- Optimized: Performance-focused with complexity trade-offs
+- Hybrid: Balanced approach with configurable optimization
+- Novel: Innovative approaches using new techniques
+
+Architectural Variations:
+- Monolithic: Single deployment unit with tight coupling
+- Modular: Loosely coupled modules within single codebase
+- Microservices: Distributed services with independent deployment
+- Serverless: Function-based with cloud provider management
+
+Technology Stack Variations:
+- Traditional: Established, well-documented technologies
+- Modern: Current best practices and recent frameworks
+- Cutting-edge: Latest technologies with higher risk/reward
+- Hybrid: Mix of established and modern approaches
+
+Performance Profile Variations:
+- Memory-optimized: Minimal memory footprint
+- Speed-optimized: Maximum execution performance  
+- Scalability-optimized: Handles growth efficiently
+- Maintainability-optimized: Easy to modify and extend
+```
+
+#### Variation Specification Framework
+```
+For each code variation:
+
+Implementation Details:
+- Core Algorithm/Approach: [specific technical approach]
+- Key Dependencies: [frameworks, libraries, external services]
+- Architecture Pattern: [structural organization approach]
+- Data Flow Design: [how information moves through system]
+
+Quality Characteristics:
+- Performance Profile: [speed, memory, throughput expectations]
+- Maintainability Score: [ease of modification and extension]
+- Scalability Potential: [growth and load handling capability]
+- Reliability Assessment: [error handling and fault tolerance]
+
+Resource Requirements:
+- Development Time: [estimated implementation effort]
+- Team Skill Requirements: [expertise needed for implementation]
+- Infrastructure Needs: [deployment and operational requirements]
+- Ongoing Maintenance: [long-term support and evolution needs]
+```
+
+### 3. Simulation Framework Design
+
+**Create testing environment for code variations:**
+
+#### Code Simulation Methodology
+```
+Multi-Dimensional Testing Approach:
+
+Performance Simulation:
+- Synthetic workload generation and stress testing
+- Memory usage profiling and leak detection
+- Concurrent execution and race condition testing
+- Resource utilization monitoring and optimization
+
+Maintainability Simulation:
+- Code complexity analysis and metrics calculation
+- Change impact simulation and ripple effect analysis
+- Documentation quality and developer onboarding simulation
+- Debugging and troubleshooting ease assessment
+
+Scalability Simulation:
+- Load growth simulation and performance degradation analysis
+- Horizontal scaling simulation and resource efficiency
+- Data volume growth impact and query performance
+- Integration point stress testing and failure handling
+
+Security Simulation:
+- Attack vector simulation and vulnerability assessment
+- Data protection and privacy compliance testing
+- Authentication and authorization load testing
+- Input validation and sanitization effectiveness
+```
+
+#### Testing Environment Setup
+- Isolated testing environments for each variation
+- Consistent data sets and test scenarios across variations
+- Automated testing pipeline and result collection
+- Realistic production environment simulation
+
+### 4. Quality Gate Framework
+
+**Establish systematic evaluation criteria:**
+
+#### Multi-Criteria Evaluation Matrix
+```
+Code Quality Assessment Framework:
+
+Performance Gates (25% weight):
+- Response Time: [acceptable latency thresholds]
+- Throughput: [minimum requests/transactions per second]
+- Resource Usage: [memory, CPU, storage efficiency]
+- Scalability: [performance degradation under load]
+
+Maintainability Gates (25% weight):
+- Code Complexity: [cyclomatic complexity, nesting levels]
+- Test Coverage: [unit, integration, end-to-end test coverage]
+- Documentation Quality: [code comments, API docs, architecture docs]
+- Change Impact: [blast radius of typical modifications]
+
+Reliability Gates (25% weight):
+- Error Handling: [graceful failure and recovery mechanisms]
+- Fault Tolerance: [system behavior under adverse conditions]
+- Data Integrity: [consistency and corruption prevention]
+- Monitoring/Observability: [debugging and operational visibility]
+
+Business Gates (25% weight):
+- Time to Market: [development speed and delivery timeline]
+- Total Cost of Ownership: [development + operational costs]
+- Risk Assessment: [technical and business risk factors]
+- Strategic Alignment: [fit with long-term technology direction]
+
+Gate Score = (Performance × 0.25) + (Maintainability × 0.25) + (Reliability × 0.25) + (Business × 0.25)
+```
+
+#### Threshold Management
+- Minimum acceptable scores for each quality dimension
+- Trade-off analysis for competing quality attributes
+- Conditional gates based on specific use case requirements
+- Risk-adjusted thresholds for different implementation approaches
+
+### 5. Predictive Performance Modeling
+
+**Forecast real-world behavior before implementation:**
+
+#### Performance Prediction Framework
+```
+Multi-Layer Performance Modeling:
+
+Micro-Benchmarks:
+- Individual function and method performance measurement
+- Algorithm complexity analysis and big-O verification
+- Memory allocation patterns and garbage collection impact
+- CPU instruction efficiency and optimization opportunities
+
+Integration Performance:
+- Inter-module communication overhead and optimization
+- Database query performance and connection pooling
+- External API latency and timeout handling
+- Caching strategy effectiveness and hit ratio analysis
+
+System-Level Performance:
+- End-to-end request processing and user experience
+- Concurrent user simulation and resource contention
+- Peak load handling and graceful degradation
+- Infrastructure scaling behavior and cost implications
+
+Production Environment Prediction:
+- Real-world data volume and complexity simulation
+- Production traffic pattern modeling and capacity planning
+- Deployment and rollback performance impact assessment
+- Operational monitoring and alerting effectiveness
+```
+
+#### Confidence Interval Calculation
+- Statistical analysis of performance variation across test runs
+- Confidence levels for performance predictions under different conditions
+- Sensitivity analysis for key performance parameters
+- Risk assessment for performance-related business impacts
+
+### 6. Risk and Trade-off Analysis
+
+**Systematic evaluation of implementation choices:**
+
+#### Technical Risk Assessment
+```
+Risk Evaluation Framework:
+
+Implementation Risks:
+- Technical Complexity: [difficulty and error probability]
+- Dependency Risk: [external library and service dependencies]
+- Performance Risk: [ability to meet performance requirements]
+- Integration Risk: [compatibility with existing systems]
+
+Operational Risks:
+- Deployment Complexity: [rollout difficulty and rollback capability]
+- Monitoring/Debugging: [operational visibility and troubleshooting]
+- Scaling Challenges: [growth accommodation and resource planning]
+- Maintenance Burden: [ongoing support and evolution requirements]
+
+Business Risks:
+- Timeline Risk: [delivery schedule and market timing impact]
+- Resource Risk: [team capacity and skill requirements]
+- Opportunity Cost: [alternative approaches and strategic alignment]
+- Competitive Risk: [technology choice and market position impact]
+```
+
+#### Trade-off Optimization
+- Pareto frontier analysis for competing objectives
+- Multi-objective optimization for quality attributes
+- Scenario-based trade-off evaluation
+- Stakeholder preference weighting and consensus building
+
+### 7. Decision Matrix and Recommendations
+
+**Generate systematic implementation guidance:**
+
+#### Code Variation Evaluation Summary
+```
+## Code Permutation Analysis: [Feature/Module Name]
+
+### Variation Comparison Matrix
+
+| Variation | Performance | Maintainability | Reliability | Business | Overall Score |
+|-----------|-------------|-----------------|-------------|----------|---------------|
+| Approach A | 85% | 70% | 90% | 75% | 80% |
+| Approach B | 70% | 90% | 80% | 85% | 81% |
+| Approach C | 95% | 60% | 70% | 65% | 73% |
+
+### Detailed Analysis
+
+#### Recommended Approach: [Selected Variation]
+
+**Rationale:**
+- Performance Advantages: [specific benefits and measurements]
+- Maintainability Considerations: [long-term support implications]
+- Risk Assessment: [identified risks and mitigation strategies]
+- Business Alignment: [strategic fit and market timing]
+
+**Implementation Plan:**
+- Development Phases: [staged implementation approach]
+- Quality Checkpoints: [validation gates and success criteria]
+- Risk Mitigation: [specific risk reduction strategies]
+- Performance Validation: [ongoing monitoring and optimization]
+
+#### Alternative Considerations:
+- Backup Option: [second-choice approach and trigger conditions]
+- Hybrid Opportunities: [combining best elements from multiple approaches]
+- Future Evolution: [how to migrate or improve chosen approach]
+- Context Dependencies: [when alternative approaches might be better]
+
+### Success Metrics and Monitoring
+- Performance KPIs: [specific metrics and acceptable ranges]
+- Quality Indicators: [maintainability and reliability measures]
+- Business Outcomes: [user satisfaction and business impact metrics]
+- Early Warning Signs: [indicators that approach is not working]
+```
+
+### 8. Continuous Learning Integration
+
+**Establish feedback loops for approach refinement:**
+
+#### Implementation Validation
+- Real-world performance comparison to simulation predictions
+- Developer experience and productivity measurement
+- User feedback and satisfaction assessment
+- Business outcome tracking and success evaluation
+
+#### Knowledge Capture
+- Decision rationale documentation and lessons learned
+- Best practice identification and pattern library development
+- Anti-pattern recognition and avoidance strategies
+- Team capability building and expertise development
+
+## Usage Examples
+
+```bash
+# Algorithm optimization testing
+/dev:code-permutation-tester Test 5 different sorting algorithms for large dataset processing with memory and speed constraints
+
+# Architecture pattern evaluation
+/dev:code-permutation-tester Compare microservices vs monolith vs modular monolith for payment processing system
+
+# Framework selection simulation
+/dev:code-permutation-tester Evaluate React vs Vue vs Angular for customer dashboard with performance and maintainability focus
+
+# Database optimization testing
+/dev:code-permutation-tester Test NoSQL vs relational vs hybrid database approaches for user analytics platform
+```
+
+## Quality Indicators
+
+- **Green**: Multiple variations tested, comprehensive quality gates, validated performance predictions
+- **Yellow**: Some variations tested, basic quality assessment, estimated performance  
+- **Red**: Single approach, minimal testing, unvalidated assumptions
+
+## Common Pitfalls to Avoid
+
+- Premature optimization: Over-engineering for theoretical rather than real requirements
+- Analysis paralysis: Testing too many variations without making decisions
+- Context ignorance: Not considering real-world constraints and team capabilities
+- Quality tunnel vision: Optimizing for single dimension while ignoring others
+- Simulation disconnect: Testing scenarios that don't match production reality
+- Decision delay: Not acting on simulation results in timely manner
+
+Transform code implementation from guesswork into systematic, evidence-based decision making through comprehensive variation testing and simulation.