ai-playbook 1.0.0

package/skills/performance/skill.md

@@ -0,0 +1,199 @@
+# Performance Skill
+
+## Purpose
+
+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 metrics and measurement, profiling and analysis techniques, code and database optimization, infrastructure optimization, and load testing strategies. Performance engineering is about making data-driven optimization decisions rather than premature or speculative improvements.
+
+---
+
+## Table of Contents
+
+1. [Core Competencies](#core-competencies)
+2. [Specific Domains & Tools](#specific-domains--tools)
+3. [Best Practices](#best-practices)
+4. [Deliverables](#deliverables)
+5. [Success Criteria](#success-criteria)
+
+---
+
+## Core Competencies
+
+### 1. **Performance Measurement & Metrics**
+Establish clear performance metrics aligned with user experience and business goals. Measure response times (p50, p95, p99), throughput, error rates, and resource utilization. Distinguish between synthetic monitoring (controlled tests) and real user monitoring (production data). Track trends over time.
+
+**Application**: Setting performance goals, monitoring progress, detecting regressions, understanding performance distribution.
+
+### 2. **Profiling & Performance Analysis**
+Use profiling tools to identify bottlenecks and understand where time is spent. Conduct CPU profiling to find hot code paths. Analyze memory usage and garbage collection impact. Trace database queries and network calls. Use flame graphs to visualize call stacks.
+
+**Application**: Finding optimization opportunities, understanding bottlenecks, prioritizing optimization efforts, validating optimizations.
+
+### 3. **Algorithm & Code Optimization**
+Optimize code for better algorithmic complexity, memory efficiency, and CPU performance. Improve loop efficiency, reduce memory allocations, optimize string operations. Optimize concurrency and synchronization patterns. Balance code clarity with performance.
+
+**Application**: Reducing CPU usage, improving responsiveness, enabling scaling, reducing memory footprint.
+
+### 4. **Database Performance Optimization**
+Optimize database queries and schema design for performance. Create appropriate indexes, analyze query execution plans, optimize for access patterns. Implement query result caching, connection pooling, and batch operations. Plan for database scaling through replication and partitioning.
+
+**Application**: Reducing query latency, improving throughput, enabling database scaling, reducing database load.
+
+### 5. **Caching Strategy Design**
+Design multi-level caching strategies that improve performance while maintaining consistency. Implement in-process caching, distributed caching, and HTTP caching. Design cache invalidation strategies that balance freshness and performance. Plan cache warming strategies.
+
+**Application**: Reducing latency, reducing database load, improving hit rates, enabling scalability.
+
+### 6. **Infrastructure & Resource Optimization**
+Optimize infrastructure for performance through proper sizing, configuration, and resource allocation. Plan for load balancing, auto-scaling, and resource constraints. Optimize CPU, memory, disk I/O, and network usage. Design for efficient resource utilization.
+
+**Application**: Improving throughput, reducing latency, optimizing costs, enabling scaling.
+
+### 7. **Load Testing & Capacity Planning**
+Design and execute load tests that validate performance at expected scale. Create baseline tests, ramp-up tests, spike tests, and sustained load tests. Identify performance degradation patterns. Plan capacity based on growth projections.
+
+**Application**: Validating scalability, finding bottlenecks under load, capacity planning, testing disaster recovery.
+
+### 8. **Frontend Performance Optimization**
+Optimize browser-based performance through JavaScript optimization, CSS optimization, image optimization, and asset loading strategies. Implement code splitting, lazy loading, and progressive rendering. Optimize for Core Web Vitals (LCP, FID, CLS).
+
+**Application**: Improving page load times, improving Core Web Vitals, reducing JavaScript bundle size, improving user experience.
+
+### 9. **Network & CDN Optimization**
+Optimize network utilization and latency through CDN usage, compression, connection pooling, and protocol optimization. Reduce payload sizes, minimize round trips, and leverage edge caching. Optimize for slow networks and high latency scenarios.
+
+**Application**: Improving responsiveness for geographically distributed users, reducing bandwidth costs, improving load times.
+
+### 10. **Concurrency & Parallelization**
+Design systems that effectively use concurrency for improved performance. Implement thread pools, async/await patterns, and reactive programming. Optimize for multi-core systems. Manage contention and synchronization overhead.
+
+**Application**: Improving throughput, improving responsiveness under concurrent load, enabling scaling.
+
+### 11. **Memory Optimization**
+Optimize memory usage through efficient data structures, garbage collection tuning, and memory pooling. Reduce memory leaks and unnecessary allocations. Optimize object reuse. Design for memory-constrained environments.
+
+**Application**: Reducing memory footprint, improving garbage collection performance, enabling deployment on smaller machines.
+
+### 12. **Distributed System Performance**
+Design distributed systems for performance considering latency, throughput, and consistency trade-offs. Optimize for network latency and bandwidth. Minimize inter-service communication. Design for efficient data partitioning.
+
+**Application**: Designing high-performance distributed systems, optimizing service-to-service communication, scaling to large systems.
+
+### 13. **Real User Monitoring (RUM)**
+Implement monitoring that captures real user experience in production. Collect performance metrics from actual browsers and devices. Identify performance issues affecting real users. Segment performance by user, device, and network characteristics.
+
+**Application**: Understanding real-world performance, detecting regressions in production, identifying user experience issues.
+
+### 14. **Performance Budgets & Regression Detection**
+Establish performance budgets that prevent regressions. Implement automated detection of performance regressions. Create performance SLOs. Monitor trends to detect subtle performance degradation.
+
+**Application**: Preventing performance regressions, maintaining performance over time, early detection of issues.
+
+### 15. **Scalability Analysis & Planning**
+Analyze systems for scalability limitations. Identify bottlenecks that prevent scaling. Plan for growth and future requirements. Design for horizontal and vertical scalability.
+
+**Application**: Capacity planning, preventing scalability surprises, enabling growth, planning infrastructure expansion.
+
+### 16. **Benchmarking & Comparison**
+Design benchmarks that accurately measure performance improvements. Compare performance before and after optimization. Use appropriate metrics for comparison. Account for variability in measurements.
+
+**Application**: Validating optimization impact, comparing alternatives, tracking progress.
+
+### 17. **Performance Debugging & Root Cause Analysis**
+Systematically debug performance issues to find root causes. Use profilers, traces, and logs to understand behavior. Test hypotheses about performance issues. Validate fixes.
+
+**Application**: Finding performance issues, understanding unexpected behavior, validating fixes.
+
+### 18. **Trade-off Analysis & Decision Making**
+Analyze trade-offs between performance, maintainability, complexity, and other concerns. Make informed decisions about optimization. Document rationale for performance decisions.
+
+**Application**: Deciding what to optimize, balancing concerns, justifying optimization efforts.
+
+---
+
+## Specific Domains & Tools
+
+### Profiling Tools
+- **CPU Profilers**: perf, py-spy, Java Flight Recorder, Chrome DevTools
+- **Memory Profilers**: Valgrind, Java Flight Recorder, Chrome DevTools
+- **Network Analysis**: Wireshark, Chrome DevTools, network monitoring tools
+- **Tracing Tools**: Jaeger, Zipkin, distributed tracing platforms
+
+### Performance Measurement
+- **Synthetic Monitoring**: Lighthouse, WebPageTest, k6, JMeter
+- **Real User Monitoring**: Google Analytics, Sentry, New Relic
+- **APM Tools**: Datadog, New Relic, Elastic APM
+- **Metrics**: Prometheus, Grafana, time-series databases
+
+### Load Testing Tools
+- **k6**: Modern load testing platform
+- **Apache JMeter**: Open-source load testing
+- **Gatling**: Scala-based load testing
+- **Locust**: Python-based load testing
+
+### Frontend Performance
+- **Webpack**: JavaScript bundling and optimization
+- **Lighthouse**: Performance auditing
+- **Chrome DevTools**: Browser performance profiling
+- **Web Vitals**: Core Web Vitals measurement
+
+### Database Tools
+- **EXPLAIN plans**: Query analysis
+- **Slow query logs**: Query performance monitoring
+- **Database profilers**: Detailed database performance analysis
+- **Index analysis tools**: Index optimization recommendations
+
+---
+
+## Best Practices
+
+1. **Measure Before Optimizing**: Use data to identify bottlenecks. Don't optimize speculatively. Profile to understand current behavior.
+
+2. **Focus on Bottlenecks First**: Address the 20% of code that uses 80% of resources. Optimize the hottest paths first.
+
+3. **Set Clear Performance Goals**: Establish targets for response time, throughput, and resource utilization. Align with user experience requirements.
+
+4. **Test Optimizations Thoroughly**: Validate that optimizations actually improve performance. Measure before and after. Look for regressions.
+
+5. **Monitor in Production**: Don't rely only on synthetic monitoring. Monitor real users. Detect regressions early.
+
+6. **Consider Trade-offs**: Optimization often involves trade-offs with maintainability, complexity, or readability. Evaluate trade-offs.
+
+7. **Think Globally**: Consider entire system performance, not just individual components. Optimize bottlenecks, not randomly.
+
+8. **Automate Performance Testing**: Include performance tests in CI/CD. Detect regressions automatically.
+
+9. **Document Decisions**: Explain why optimizations were made. Document performance trade-offs.
+
+10. **Iterate & Measure**: Optimization is iterative. Measure progress. Set new goals as old ones are met.
+
+---
+
+## Deliverables
+
+- **Performance Analysis Report**: Bottleneck identification and optimization recommendations
+- **Performance Baselines**: Current performance metrics and targets
+- **Load Test Results**: Capacity and scalability findings
+- **Optimization Plan**: Prioritized list of optimizations with estimated impact
+- **Performance Dashboards**: Real-time performance monitoring
+- **Performance Budgets**: Defined performance targets and monitoring
+- **Benchmarking Results**: Before/after comparison of optimizations
+- **Profiling Reports**: Detailed analysis of code/system performance
+- **Scalability Assessment**: Analysis of scaling limitations and recommendations
+- **Monitoring Configuration**: Alerts and metrics for ongoing performance tracking
+- **Tuning Recommendations**: System configuration optimizations
+- **Documentation**: Performance goals, optimization decisions, and trade-offs
+
+---
+
+## Success Criteria
+
+1. **Goals Met**: System meets established performance targets (response time, throughput)
+2. **Bottlenecks Eliminated**: Primary performance bottlenecks identified and addressed
+3. **Scalable**: System scales to handle growth without performance degradation
+4. **Maintainable**: Optimizations don't compromise code quality or maintainability
+5. **Monitored**: Performance monitored continuously with regressions detected early
+6. **Consistent**: Performance consistent across different scenarios and load patterns
+7. **Documented**: Performance goals and decisions documented clearly
+8. **Sustainable**: Performance improvements sustained over time without ongoing tuning
+9. **Proportional**: Optimization effort proportional to impact
+10. **User Experience**: End users perceive responsive, fast system

package/skills/qa/README.md

@@ -0,0 +1,106 @@
+# Quality Assurance (QA)
+
+## Overview
+
+The **QA** skill enables AI models to design, implement, execute, and maintain comprehensive quality assurance strategies that ensure software reliability, functionality, security, performance, and user satisfaction throughout the development lifecycle.
+
+This skill covers test planning, test execution, test automation, defect management, and quality metrics across multiple testing types and platforms.
+
+---
+
+# Goals
+
+* Design comprehensive test strategies
+* Identify defects before production
+* Achieve defined coverage targets
+* Execute tests efficiently and reliably
+* Provide clear quality visibility
+* Enable confident deployments
+* Support rapid iteration cycles
+* Maintain quality consistently
+
+---
+
+# Capabilities
+
+## Test Planning
+* Test strategy design
+* Test plan development
+* Risk-based testing
+* Coverage planning
+
+## Testing Types
+* Functional testing
+* Non-functional testing
+* Regression testing
+* User acceptance testing
+* Exploratory testing
+
+## Automation
+* Test automation design
+* Test framework selection
+* Test data management
+* CI/CD integration
+
+## Defect Management
+* Defect triage and prioritization
+* Root cause analysis
+* Defect tracking and metrics
+
+---
+
+# When to Use
+
+* Planning testing strategy
+* Creating test cases
+* Setting up test automation
+* Analyzing defects
+* Improving test coverage
+* Conducting security/performance testing
+* Preparing for releases
+
+---
+
+# Expected Workflow
+
+```
+Define Requirements
+        ↓
+Design Test Strategy
+        ↓
+Create Test Cases
+        ↓
+Execute Tests
+        ↓
+Analyze Defects
+        ↓
+Report Results
+        ↓
+Iterate & Improve
+```
+
+---
+
+# Best Practices
+
+Always:
+* Define clear test objectives
+* Design tests based on requirements
+* Execute in controlled environments
+* Document findings thoroughly
+* Prioritize critical functionality
+* Keep tests maintainable
+* Track metrics consistently
+
+Never:
+* Test in production
+* Skip regression testing
+* Assume testing is unneeded
+* Ignore performance issues
+* Skip accessibility testing
+
+---
+
+# Success Criteria
+
+Successful QA should identify defects before production, achieve coverage targets, provide reliable results, enable confident deployments, and maintain quality consistently.

package/skills/qa/examples.md

@@ -0,0 +1,84 @@
+# QA Skill - Examples
+
+This document contains practical examples demonstrating when and how to use the QA Skill.
+
+---
+
+# Example 1 - Test Plan Development
+
+## User Request
+Create a comprehensive test plan for a new user authentication feature.
+
+## Expected Behavior
+* Define test scope and objectives
+* Identify test levels (unit, integration, system, acceptance)
+* Design test cases for happy path and edge cases
+* Plan for security testing
+* Define entry and exit criteria
+* Estimate testing effort and timeline
+
+---
+
+# Example 2 - Test Automation Strategy
+
+## User Request
+Design a test automation strategy for this REST API.
+
+## Expected Behavior
+* Identify which tests to automate
+* Choose appropriate testing framework
+* Design test data strategy
+* Plan API test coverage
+* Create test execution pipeline
+* Design error handling and retries
+
+---
+
+# Example 3 - Performance Testing
+
+## User Request
+Design and execute performance tests for this API.
+
+## Expected Behavior
+* Define performance objectives
+* Design load scenarios
+* Create test data
+* Execute load tests
+* Analyze results
+* Recommend optimizations
+
+---
+
+# Example 4 - Security Testing
+
+## User Request
+Plan security testing for this payment processing system.
+
+## Expected Behavior
+* Identify security risks
+* Design security test cases
+* Test authentication/authorization
+* Verify encryption
+* Test input validation
+* Create security test report
+
+---
+
+# Example 5 - Accessibility Testing
+
+## User Request
+Verify this web application meets WCAG AA standards.
+
+## Expected Behavior
+* Check color contrast
+* Verify keyboard navigation
+* Test screen reader compatibility
+* Validate form accessibility
+* Document issues found
+* Plan for continuous verification
+
+---
+
+# Success Criteria
+
+A successful QA effort should find defects before production, achieve coverage targets, execute efficiently, provide visibility, and enable confident deployments.