ai-playbook 1.0.0

package/skills/performance/README.md

@@ -0,0 +1,177 @@
+# Performance Skill
+
+## Overview
+
+The Performance skill enables the analysis, optimization, and sustainment of software system performance to meet response time, throughput, and resource utilization goals while maintaining scalability and reliability. This skill encompasses performance measurement and metrics, profiling and bottleneck identification, code and database optimization, caching strategy design, load testing and capacity planning, and continuous performance monitoring. Performance engineering is data-driven optimization focused on eliminating real bottlenecks rather than speculative improvements.
+
+---
+
+## Goals
+
+- **Identify Bottlenecks**: Use profiling and analysis to find where time is spent and what constrains performance
+- **Optimize Systematically**: Make data-driven optimization decisions, focusing on high-impact bottlenecks first
+- **Meet Performance Targets**: Achieve response time and throughput goals aligned with user experience and business requirements
+- **Enable Scalability**: Design systems that scale to handle growth without performance degradation
+- **Prevent Regressions**: Monitor continuously and detect performance regressions early
+- **Optimize Costs**: Improve performance per dollar spent on infrastructure
+- **Sustain Performance**: Create systems that maintain good performance over time without ongoing tuning
+- **Improve User Experience**: Make applications feel responsive and fast to end users
+
+---
+
+## Capabilities
+
+### Performance Analysis
+- **Profiling**: CPU, memory, and I/O profiling to identify hot code paths
+- **Bottleneck Identification**: Finding performance-limiting components
+- **Metrics Collection**: Response time, throughput, resource utilization, error rates
+- **Trend Analysis**: Detecting performance changes over time
+- **Distributed Tracing**: Understanding performance across service boundaries
+
+### Optimization Domains
+- **Code Optimization**: Algorithm efficiency, memory usage, CPU utilization
+- **Database Optimization**: Query performance, indexing, query caching
+- **Caching Strategies**: Multi-level caching, cache invalidation, cache warming
+- **Infrastructure Optimization**: Resource allocation, load balancing, auto-scaling
+- **Frontend Performance**: JavaScript bundling, image optimization, Core Web Vitals
+
+### Load & Capacity Testing
+- **Load Testing**: Baseline, ramp-up, sustained, spike testing
+- **Stress Testing**: Finding breaking points and limits
+- **Capacity Planning**: Projecting performance at different scales
+- **Endurance Testing**: Long-running stability and performance
+- **Volume Testing**: Performance with large data sets
+
+### Monitoring & Alerting
+- **Performance Dashboards**: Real-time visibility into system performance
+- **Real User Monitoring**: Actual user experience metrics
+- **Synthetic Monitoring**: Controlled performance testing
+- **Alert Configuration**: Detecting performance anomalies
+- **Performance Budgets**: Preventing regressions
+
+### Specialized Optimization
+- **Search & Indexing**: Full-text search, database index optimization
+- **Memory Management**: Garbage collection tuning, memory profiling
+- **Concurrency**: Thread pools, async patterns, parallelization
+- **Network**: Compression, CDN, connection pooling, protocol optimization
+
+---
+
+## When to Use
+
+**Use this skill when you need to:**
+- Investigate why a system is slow or not meeting performance targets
+- Design system architecture for performance and scalability
+- Conduct load testing before major releases
+- Optimize database queries or slow operations
+- Reduce resource consumption (memory, CPU, bandwidth)
+- Implement caching strategies
+- Set up performance monitoring and alerting
+- Plan capacity for expected growth
+- Detect and diagnose performance regressions
+- Optimize user-facing latency (Core Web Vitals, frontend performance)
+
+**Typical scenarios:**
+- Production performance issues investigation
+- Pre-launch performance validation
+- Capacity planning for growth
+- Infrastructure cost optimization
+- Performance regression detection
+- System redesign for scalability
+- Code optimization for specific bottlenecks
+
+---
+
+## Expected Workflow
+
+```
+Define Performance Goals & Constraints
+        ↓
+Measure Current Performance
+        ↓
+Identify Bottlenecks via Profiling
+        ↓
+Analyze Root Causes
+        ↓
+Design Optimization Strategies
+        ↓
+Implement Optimizations
+        ↓
+Measure & Validate Improvements
+        ↓
+Load Test at Scale
+        ↓
+Monitor Continuously
+        ↓
+Iterate & Improve
+```
+
+---
+
+## Inputs
+
+- **Performance Targets**: Expected response time, throughput, resource usage goals
+- **Current Metrics**: Baseline performance data (latency, throughput, resource utilization)
+- **Workload Profile**: Typical query/request patterns, data sizes
+- **Constraints**: Budget, infrastructure limitations, team expertise
+- **Growth Projections**: Expected growth in load, data, and users
+- **Business Requirements**: SLO targets, user experience expectations
+- **System Information**: Architecture, technology stack, existing optimizations
+- **Production Data**: Real user performance, error rates, monitoring data
+
+---
+
+## Outputs
+
+- **Performance Analysis Report**: Bottleneck identification and root cause analysis
+- **Optimization Plan**: Prioritized list of optimizations with impact estimates
+- **Load Testing Results**: Capacity findings and scalability assessment
+- **Performance Baselines**: Current performance metrics and targets
+- **Implementation Guide**: Step-by-step optimization implementation
+- **Monitoring Configuration**: Dashboards, alerts, performance budgets
+- **Benchmarking Results**: Before/after comparison of optimizations
+- **Scalability Report**: Analysis of scaling limitations and solutions
+- **Cost Analysis**: Resource utilization and cost optimization opportunities
+- **Documentation**: Performance goals, decisions, and trade-offs
+
+---
+
+## Related Skills
+
+- **Architecture**: System design for performance, scalability patterns
+- **DevOps**: Infrastructure optimization, monitoring setup, load testing
+- **Software Development**: Code quality, algorithm design, memory management
+- **Database**: Query optimization, indexing, schema design
+- **Frontend Development**: JavaScript optimization, bundle size, Core Web Vitals
+
+---
+
+## Best Practices
+
+1. **Measure Before Optimizing**: Use profiling and metrics to identify bottlenecks. Don't optimize speculatively
+2. **Focus on Bottlenecks**: Address the 20% of code that uses 80% of resources
+3. **Set Clear Goals**: Define performance targets aligned with user experience and business needs
+4. **Test Optimizations**: Validate that changes actually improve performance; measure before and after
+5. **Monitor Continuously**: Don't rely on synthetic testing alone; monitor real user performance
+6. **Consider Trade-offs**: Optimization often involves trade-offs with maintainability or complexity
+7. **Think Globally**: Consider system-wide performance, not just individual components
+8. **Automate Performance Testing**: Include performance tests in CI/CD to detect regressions
+9. **Document Decisions**: Explain why optimizations were made and what trade-offs were accepted
+10. **Iterate & Measure**: Optimization is iterative; measure progress and adjust approach
+
+---
+
+## Success Criteria
+
+1. **Goals Met**: System meets established performance targets
+2. **Bottlenecks Removed**: Primary bottlenecks identified and addressed
+3. **Scalable**: Scales to expected load without performance degradation
+4. **Monitored**: Performance continuously monitored with regressions detected quickly
+5. **Sustainable**: Performance improvements maintained without ongoing tuning
+6. **Efficient**: Resource utilization optimized (CPU, memory, network)
+7. **Consistent**: Performance consistent across different scenarios and load patterns
+8. **Maintainable**: Optimizations don't compromise code quality or readability
+9. **Documented**: Clear documentation of performance goals and optimization decisions
+10. **User Experience**: End users perceive responsive, fast system
+
+---

package/skills/performance/examples.md

@@ -0,0 +1,376 @@
+# Performance Skill - Examples
+
+## Example 1: API Performance Analysis & Optimization
+
+**User Request**: "Our API serves 1000 requests/second but latency is 800ms p99. Analyze and optimize."
+
+**Expected Behavior**:
+- Profile the API endpoint to identify hot code paths
+- Analyze database query execution times
+- Check for N+1 query problems
+- Analyze memory allocation patterns
+- Profile cache hit rates
+- Measure serialization overhead
+- Use distributed tracing to identify bottlenecks
+- Create optimization plan with impact estimates
+- Implement optimizations (caching, query optimization, code optimization)
+- Measure improvement and validate goals
+
+**Success Criteria**:
+- P99 latency reduced to <100ms
+- Throughput increases to handle spikes
+- Memory usage reduced by 30%+
+- Cache hit rate >85%
+- No regressions in accuracy/functionality
+
+---
+
+## Example 2: Load Testing & Capacity Planning
+
+**User Request**: "Product launches next month with expected 10x traffic. Design load testing to validate system can handle it."
+
+**Expected Behavior**:
+- Design load testing scenarios matching expected traffic patterns
+- Create baseline test with current load
+- Execute ramp-up test to identify breaking points
+- Conduct sustained load test at 10x expected traffic
+- Execute spike tests to simulate traffic bursts
+- Identify bottlenecks and saturation points
+- Measure resource utilization under load (CPU, memory, database, network)
+- Analyze response time distribution at load
+- Identify auto-scaling triggers
+- Create capacity planning recommendations
+
+**Success Criteria**:
+- System handles 10x traffic with <200ms p99 latency
+- Auto-scaling activates appropriately
+- No timeouts or connection failures
+- Resource utilization <80% at peak load
+- Recovery from spikes within 5 minutes
+
+---
+
+## Example 3: Database Query Optimization
+
+**User Request**: "A user profile query takes 500ms. Optimize it."
+
+**Expected Behavior**:
+- Capture slow query with execution plan
+- Analyze query execution plan for inefficiencies
+- Identify missing indexes
+- Check for N+1 query problems
+- Analyze join strategies
+- Recommend denormalization if appropriate
+- Implement caching layer for frequently accessed data
+- Optimize query structure
+- Rewrite using better patterns if needed
+- Measure improvement
+
+**Success Criteria**:
+- Query latency reduced to <10ms
+- No full table scans
+- Indexes used appropriately
+- Cache hit rate >90%
+- Explains clearly why optimization worked
+
+---
+
+## Example 4: Frontend Performance Optimization
+
+**User Request**: "Our web app takes 6 seconds to load. Improve Core Web Vitals to pass assessment."
+
+**Expected Behavior**:
+- Analyze Lighthouse report to identify issues
+- Measure Core Web Vitals (LCP, FID, CLS)
+- Analyze asset sizes and load waterfall
+- Identify slow JavaScript execution
+- Design code splitting and lazy loading strategy
+- Optimize image sizes and formats
+- Implement critical CSS inlining
+- Reduce third-party scripts impact
+- Implement service worker caching
+- Monitor with real user monitoring
+
+**Success Criteria**:
+- Largest Contentful Paint (LCP) <2.5 seconds
+- Cumulative Layout Shift (CLS) <0.1
+- First Input Delay (FID) <100ms
+- Overall page load <3 seconds
+- Lighthouse score >90
+
+---
+
+## Example 5: Caching Strategy Design
+
+**User Request**: "Database is CPU-bound serving repeated queries. Design caching to reduce load by 50%."
+
+**Expected Behavior**:
+- Analyze query patterns to identify cache opportunities
+- Design multi-level caching (in-process + distributed)
+- Choose cache technology (Redis, Memcached, etc.)
+- Design cache key strategy
+- Implement cache invalidation strategy
+- Design cache warming for predictable data
+- Implement circuit breaker for cache failures
+- Create monitoring for cache hit rates
+- Design for graceful degradation if cache fails
+- Measure impact on database load and response times
+
+**Success Criteria**:
+- Database CPU load reduced by 50%
+- Cache hit rate >80% for target queries
+- Cache failures don't cause cascading failures
+- Response times for cached queries <5ms
+- Cache consistency maintained
+
+---
+
+## Example 6: Distributed System Performance
+
+**User Request**: "Microservices architecture has high latency due to service-to-service communication. Optimize."
+
+**Expected Behavior**:
+- Map service-to-service dependencies
+- Profile network latency and payload sizes
+- Identify unnecessary service calls
+- Design request batching where appropriate
+- Implement caching of service responses
+- Design service mesh optimization
+- Consider GraphQL/composite API patterns
+- Reduce payload sizes through selective field inclusion
+- Implement connection pooling
+- Optimize for network conditions
+
+**Success Criteria**:
+- P99 latency reduced from 500ms to <100ms
+- Payload sizes reduced by 30%+
+- Service-to-service call count reduced
+- Timeout errors reduced to near zero
+- User-perceived latency improves significantly
+
+---
+
+## Example 7: Memory Optimization
+
+**User Request**: "Application uses 8GB of memory. Optimize to use 2GB without losing functionality."
+
+**Expected Behavior**:
+- Profile memory usage with memory profiler
+- Identify large memory allocations
+- Analyze garbage collection pause times
+- Look for memory leaks
+- Optimize data structures (use more efficient types)
+- Reduce unnecessary object creation
+- Implement object pooling for frequently allocated objects
+- Tune garbage collection settings
+- Optimize serialization/deserialization overhead
+- Consider streaming for large data processing
+
+**Success Criteria**:
+- Memory usage reduced to 2GB
+- GC pause time reduced to <50ms
+- No memory leaks detected
+- Throughput maintained or improved
+- Stability improved with less heap pressure
+
+---
+
+## Example 8: Search & Indexing Optimization
+
+**User Request**: "Full-text search takes 2 seconds for millions of documents. Optimize."
+
+**Expected Behavior**:
+- Analyze search query patterns
+- Evaluate index structure and design
+- Implement filtering before full-text search
+- Design result caching strategy
+- Implement pagination for large result sets
+- Consider search engine optimization (Elasticsearch, etc.)
+- Design index warming strategy
+- Implement query result pagination
+- Monitor search performance over time
+- Measure index size and search throughput
+
+**Success Criteria**:
+- Search latency reduced to <200ms
+- Can handle millions of documents
+- Index size optimized
+- Query throughput improved
+- Accurate result ranking maintained
+
+---
+
+## Example 9: Real User Monitoring Implementation
+
+**User Request**: "Implement RUM to understand actual user performance and identify issues."
+
+**Expected Behavior**:
+- Implement performance metrics collection in browser
+- Track Core Web Vitals for real users
+- Segment performance by device, browser, network
+- Implement error tracking and source maps
+- Monitor JavaScript errors and stack traces
+- Track user interactions and performance
+- Create dashboards for RUM data
+- Set up alerting for performance regressions
+- Analyze user behavior correlation with performance
+- Compare performance by region/network
+
+**Success Criteria**:
+- Real user metrics collected and dashboarded
+- Performance issues identified before users complain
+- Regressions detected within 1 hour
+- Segment analysis identifies device/network issues
+- Actionable insights from data
+
+---
+
+## Example 10: Performance Regression Detection
+
+**User Request**: "Detect performance regressions automatically in CI/CD."
+
+**Expected Behavior**:
+- Establish performance baselines for key metrics
+- Implement automated performance testing in CI/CD
+- Define performance budgets for size, speed, etc.
+- Create regression detection rules
+- Implement trend analysis
+- Set up alerting for regressions
+- Create failure criteria for bad performance changes
+- Design for allowable variance in measurements
+- Implement historical tracking of performance
+- Create dashboards showing performance trends
+
+**Success Criteria**:
+- Regressions detected automatically
+- False positive rate <5%
+- Blocks bad changes from merging
+- Historical trend data shows improvement over time
+- Team confident in performance changes
+
+---
+
+## Example 11: Scalability Testing & Planning
+
+**User Request**: "Design a scalability test to plan for 100x growth over next 3 years."
+
+**Expected Behavior**:
+- Create growth projections for load
+- Design tests at 1x, 10x, 100x load
+- Identify bottlenecks at each scale
+- Test database scaling (replication, sharding, partitioning)
+- Test application auto-scaling
+- Measure resource costs at each scale
+- Identify architectural changes needed for 100x
+- Design migration path for schema changes
+- Plan infrastructure growth
+- Create capacity planning spreadsheet
+
+**Success Criteria**:
+- Can project performance at 100x load
+- Bottlenecks identified and addressed
+- Architectural changes planned
+- Cost projections for scaling
+- Migration path clear with no surprises
+
+---
+
+## Example 12: Third-Party Performance Impact
+
+**User Request**: "Analytics, tracking, and ads scripts are slowing down site. Quantify and optimize impact."
+
+**Expected Behavior**:
+- Measure performance impact of each script
+- Analyze network waterfall for script loading
+- Identify render-blocking scripts
+- Implement deferred/async loading
+- Design sandboxed execution for tracking
+- Implement facade pattern for lazy loading
+- Create performance budget for third-party code
+- Monitor for third-party script performance degradation
+- Design for graceful degradation if scripts fail
+- Communicate impact to stakeholders
+
+**Success Criteria**:
+- Third-party script impact reduced by 50%+
+- Page load time improved
+- Scripts don't block critical rendering
+- Monitoring detects issues with third-party code
+- Stakeholders understand performance trade-offs
+
+---
+
+## Example 13: Query & Analytics Optimization
+
+**User Request**: "Analytics dashboards take 30 seconds to load. Speed them up to <3 seconds."
+
+**Expected Behavior**:
+- Analyze dashboard queries and complexity
+- Identify slow aggregations
+- Design pre-computed result caching
+- Implement incremental refresh strategies
+- Optimize OLAP queries
+- Design for selective data loading
+- Implement result pagination
+- Consider data warehouse optimization
+- Design for streaming results
+- Use approximate queries where appropriate
+
+**Success Criteria**:
+- Dashboard loads in <3 seconds
+- Data freshness acceptable (<5 minutes)
+- Can handle dashboard exploration without slowdowns
+- Scales to larger datasets
+- Users happy with responsiveness
+
+---
+
+## Example 14: Container & Resource Optimization
+
+**User Request**: "Kubernetes pods are requesting too much memory. Right-size them."
+
+**Expected Behavior**:
+- Analyze current requests/limits vs actual usage
+- Profile memory usage under load
+- Identify memory spikes and leaks
+- Set appropriate requests for cost efficiency
+- Set limits that prevent OOM kills
+- Implement monitoring for memory usage
+- Design auto-scaling based on actual usage
+- Test with realistic load
+- Monitor for memory-related issues
+- Document resource allocation strategy
+
+**Success Criteria**:
+- Memory requests match actual usage
+- No OOM (out of memory) kills
+- Cost optimized by 30%+
+- System stable with appropriate headroom
+- Clear understanding of resource needs
+
+---
+
+## Example 15: End-to-End Performance Optimization
+
+**User Request**: "Complete application performance optimization from client to database. Target 50ms e2e latency."
+
+**Expected Behavior**:
+- Profile end-to-end path (browser, network, server, database)
+- Identify bottleneck in each layer
+- Optimize client-side rendering and JavaScript
+- Optimize network transfer (compression, bundling)
+- Optimize API responses (caching, pagination)
+- Optimize database queries
+- Implement multi-level caching strategy
+- Design for progressive rendering
+- Implement monitoring at each layer
+- Create performance dashboard showing all layers
+
+**Success Criteria**:
+- E2E latency reduced to <50ms
+- Each layer optimized
+- Monitoring shows performance at each layer
+- Sustainable performance maintained
+- Architecture supports future scaling
+
+---