monomind 2.7.12 → 2.7.13

package/packages/@monomind/cli/.claude/skills/performance-analysis/SKILL.md

@@ -1,560 +0,0 @@
----
-name: performance-analysis
-description: |
-  Comprehensive performance analysis, bottleneck detection, and optimization recommendations for Monomind swarms
----
-
-# Performance Analysis Skill
-
-Comprehensive performance analysis suite for identifying bottlenecks, profiling swarm operations, generating detailed reports, and providing actionable optimization recommendations.
-
-## Overview
-
-This skill consolidates all performance analysis capabilities:
-- **Bottleneck Detection**: Identify performance bottlenecks across communication, processing, memory, and network
-- **Performance Profiling**: Real-time monitoring and historical analysis of swarm operations
-- **Report Generation**: Create comprehensive performance reports in multiple formats
-- **Optimization Recommendations**: AI-powered suggestions for improving performance
-
-## Quick Start
-
-### Basic Bottleneck Detection
-```bash
-npx monomind bottleneck detect
-```
-
-### Generate Performance Report
-```bash
-npx monomind analysis performance-report --format html --include-metrics
-```
-
-### Analyze and Auto-Fix
-```bash
-npx monomind bottleneck detect --fix --threshold 15
-```
-
-## Core Capabilities
-
-### 1. Bottleneck Detection
-
-#### Command Syntax
-```bash
-npx monomind bottleneck detect [options]
-```
-
-#### Options
-- `--swarm-id, -s <id>` - Analyze specific swarm (default: current)
-- `--time-range, -t <range>` - Analysis period: 1h, 24h, 7d, all (default: 1h)
-- `--threshold <percent>` - Bottleneck threshold percentage (default: 20)
-- `--export, -e <file>` - Export analysis to file
-- `--fix` - Apply automatic optimizations
-
-#### Usage Examples
-```bash
-# Basic detection for current swarm
-npx monomind bottleneck detect
-
-# Analyze specific swarm over 24 hours
-npx monomind bottleneck detect --swarm-id swarm-123 -t 24h
-
-# Export detailed analysis
-npx monomind bottleneck detect -t 24h -e bottlenecks.json
-
-# Auto-fix detected issues
-npx monomind bottleneck detect --fix --threshold 15
-
-# Low threshold for sensitive detection
-npx monomind bottleneck detect --threshold 10 --export critical-issues.json
-```
-
-#### Metrics Analyzed
-
-**Communication Bottlenecks:**
-- Message queue delays
-- Agent response times
-- Coordination overhead
-- Memory access patterns
-- Inter-agent communication latency
-
-**Processing Bottlenecks:**
-- Task completion times
-- Agent utilization rates
-- Parallel execution efficiency
-- Resource contention
-- CPU/memory usage patterns
-
-**Memory Bottlenecks:**
-- Cache hit rates
-- Memory access patterns
-- Storage I/O performance
-- Neural pattern loading times
-- Memory allocation efficiency
-
-**Network Bottlenecks:**
-- API call latency
-- MCP communication delays
-- External service timeouts
-- Concurrent request limits
-- Network throughput issues
-
-#### Output Format
-```
-🔍 Bottleneck Analysis Report
-━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-📊 Summary
-├── Time Range: Last 1 hour
-├── Agents Analyzed: 6
-├── Tasks Processed: 42
-└── Critical Issues: 2
-
-🚨 Critical Bottlenecks
-1. Agent Communication (35% impact)
-   └── coordinator → coder-1 messages delayed by 2.3s avg
-
-2. Memory Access (28% impact)
-   └── Neural pattern loading taking 1.8s per access
-
-⚠️ Warning Bottlenecks
-1. Task Queue (18% impact)
-   └── 5 tasks waiting > 10s for assignment
-
-💡 Recommendations
-1. Switch to hierarchical topology (est. 40% improvement)
-2. Enable memory caching (est. 25% improvement)
-3. Increase agent concurrency to 8 (est. 20% improvement)
-
-✅ Quick Fixes Available
-Run with --fix to apply:
-- Enable smart caching
-- Optimize message routing
-- Adjust agent priorities
-```
-
-### 2. Performance Profiling
-
-#### Real-time Detection
-Automatic analysis during task execution:
-- Execution time vs. complexity
-- Agent utilization rates
-- Resource constraints
-- Operation patterns
-
-#### Common Bottleneck Patterns
-
-**Time Bottlenecks:**
-- Tasks taking > 5 minutes
-- Sequential operations that could parallelize
-- Redundant file operations
-- Inefficient algorithm implementations
-
-**Coordination Bottlenecks:**
-- Single agent for complex tasks
-- Unbalanced agent workloads
-- Poor topology selection
-- Excessive synchronization points
-
-**Resource Bottlenecks:**
-- High operation count (> 100)
-- Memory constraints
-- I/O limitations
-- Thread pool saturation
-
-#### MCP Integration
-```javascript
-// Check for bottlenecks in Claude Code
-mcp__monomind__bottleneck_detect({
-  timeRange: "1h",
-  threshold: 20,
-  autoFix: false
-})
-
-// Get detailed task results with bottleneck analysis
-mcp__monomind__task_results({
-  taskId: "task-123",
-  format: "detailed"
-})
-```
-
-**Result Format:**
-```json
-{
-  "bottlenecks": [
-    {
-      "type": "coordination",
-      "severity": "high",
-      "description": "Single agent used for complex task",
-      "recommendation": "Spawn specialized agents for parallel work",
-      "impact": "35%",
-      "affectedComponents": ["coordinator", "coder-1"]
-    }
-  ],
-  "improvements": [
-    {
-      "area": "execution_time",
-      "suggestion": "Use parallel task execution",
-      "expectedImprovement": "30-50% time reduction",
-      "implementationSteps": [
-        "Split task into smaller units",
-        "Spawn 3-4 specialized agents",
-        "Use mesh topology for coordination"
-      ]
-    }
-  ],
-  "metrics": {
-    "avgExecutionTime": "142s",
-    "agentUtilization": "67%",
-    "cacheHitRate": "82%",
-    "parallelizationFactor": 1.2
-  }
-}
-```
-
-### 3. Report Generation
-
-#### Command Syntax
-```bash
-npx monomind analysis performance-report [options]
-```
-
-#### Options
-- `--format <type>` - Report format: json, html, markdown (default: markdown)
-- `--include-metrics` - Include detailed metrics and charts
-- `--compare <id>` - Compare with previous swarm
-- `--time-range <range>` - Analysis period: 1h, 24h, 7d, 30d, all
-- `--output <file>` - Output file path
-- `--sections <list>` - Comma-separated sections to include
-
-#### Report Sections
-1. **Executive Summary**
-   - Overall performance score
-   - Key metrics overview
-   - Critical findings
-
-2. **Swarm Overview**
-   - Topology configuration
-   - Agent distribution
-   - Task statistics
-
-3. **Performance Metrics**
-   - Execution times
-   - Throughput analysis
-   - Resource utilization
-   - Latency breakdown
-
-4. **Bottleneck Analysis**
-   - Identified bottlenecks
-   - Impact assessment
-   - Optimization priorities
-
-5. **Comparative Analysis** (when --compare used)
-   - Performance trends
-   - Improvement metrics
-   - Regression detection
-
-6. **Recommendations**
-   - Prioritized action items
-   - Expected improvements
-   - Implementation guidance
-
-#### Usage Examples
-```bash
-# Generate HTML report with all metrics
-npx monomind analysis performance-report --format html --include-metrics
-
-# Compare current swarm with previous
-npx monomind analysis performance-report --compare swarm-123 --format markdown
-
-# Custom output with specific sections
-npx monomind analysis performance-report \
-  --sections summary,metrics,recommendations \
-  --output reports/perf-analysis.html \
-  --format html
-
-# Weekly performance report
-npx monomind analysis performance-report \
-  --time-range 7d \
-  --include-metrics \
-  --format markdown \
-  --output docs/weekly-performance.md
-
-# JSON format for CI/CD integration
-npx monomind analysis performance-report \
-  --format json \
-  --output build/performance.json
-```
-
-#### Sample Markdown Report
-```markdown
-# Performance Analysis Report
-
-## Executive Summary
-- **Overall Score**: 87/100
-- **Analysis Period**: Last 24 hours
-- **Swarms Analyzed**: 3
-- **Critical Issues**: 1
-
-## Key Metrics
-| Metric | Value | Trend | Target |
-|--------|-------|-------|--------|
-| Avg Task Time | 42s | ↓ 12% | 35s |
-| Agent Utilization | 78% | ↑ 5% | 85% |
-| Cache Hit Rate | 91% | → | 90% |
-| Parallel Efficiency | 2.3x | ↑ 0.4x | 2.5x |
-
-## Bottleneck Analysis
-### Critical
-1. **Agent Communication Delay** (Impact: 35%)
-   - Coordinator → Coder messages delayed by 2.3s avg
-   - **Fix**: Switch to hierarchical topology
-
-### Warnings
-1. **Memory Access Pattern** (Impact: 18%)
-   - Neural pattern loading: 1.8s per access
-   - **Fix**: Enable memory caching
-
-## Recommendations
-1. **High Priority**: Switch to hierarchical topology (40% improvement)
-2. **Medium Priority**: Enable memory caching (25% improvement)
-3. **Low Priority**: Increase agent concurrency to 8 (20% improvement)
-```
-
-### 4. Optimization Recommendations
-
-#### Automatic Fixes
-When using `--fix`, the following optimizations may be applied:
-
-**1. Topology Optimization**
-- Switch to more efficient topology (mesh → hierarchical)
-- Adjust communication patterns
-- Reduce coordination overhead
-- Optimize message routing
-
-**2. Caching Enhancement**
-- Enable memory caching
-- Optimize cache strategies
-- Preload common patterns
-- Implement cache warming
-
-**3. Concurrency Tuning**
-- Adjust agent counts
-- Optimize parallel execution
-- Balance workload distribution
-- Implement load balancing
-
-**4. Priority Adjustment**
-- Reorder task queues
-- Prioritize critical paths
-- Reduce wait times
-- Implement fair scheduling
-
-**5. Resource Optimization**
-- Optimize memory usage
-- Reduce I/O operations
-- Batch API calls
-- Implement connection pooling
-
-#### Performance Impact
-Typical improvements after bottleneck resolution:
-
-- **Communication**: 30-50% faster message delivery
-- **Processing**: 20-40% reduced task completion time
-- **Memory**: 40-60% fewer cache misses
-- **Network**: 25-45% reduced API latency
-- **Overall**: 25-45% total performance improvement
-
-## Advanced Usage
-
-### Continuous Monitoring
-```bash
-# Monitor performance in real-time
-npx monomind swarm monitor --interval 5
-
-# Generate hourly reports
-while true; do
-  npx monomind analysis performance-report \
-    --format json \
-    --output logs/perf-$(date +%Y%m%d-%H%M).json
-  sleep 3600
-done
-```
-
-### CI/CD Integration
-```yaml
-# .github/workflows/performance.yml
-name: Performance Analysis
-on: [push, pull_request]
-
-jobs:
-  analyze:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v2
-      - name: Run Performance Analysis
-        run: |
-          npx monomind analysis performance-report \
-            --format json \
-            --output performance.json
-      - name: Check Performance Thresholds
-        run: |
-          npx monomind bottleneck detect \
-            --threshold 15 \
-            --export bottlenecks.json
-      - name: Upload Reports
-        uses: actions/upload-artifact@v2
-        with:
-          name: performance-reports
-          path: |
-            performance.json
-            bottlenecks.json
-```
-
-### Custom Analysis Scripts
-```javascript
-// scripts/analyze-performance.js
-const { exec } = require('child_process');
-const fs = require('fs');
-
-async function analyzePerformance() {
-  // Run bottleneck detection
-  const bottlenecks = await runCommand(
-    'npx monomind bottleneck detect --format json'
-  );
-
-  // Generate performance report
-  const report = await runCommand(
-    'npx monomind analysis performance-report --format json'
-  );
-
-  // Analyze results
-  const analysis = {
-    bottlenecks: JSON.parse(bottlenecks),
-    performance: JSON.parse(report),
-    timestamp: new Date().toISOString()
-  };
-
-  // Save combined analysis
-  fs.writeFileSync(
-    'analysis/combined-report.json',
-    JSON.stringify(analysis, null, 2)
-  );
-
-  // Generate alerts if needed
-  if (analysis.bottlenecks.critical.length > 0) {
-    console.error('CRITICAL: Performance bottlenecks detected!');
-    process.exit(1);
-  }
-}
-
-function runCommand(cmd) {
-  return new Promise((resolve, reject) => {
-    exec(cmd, (error, stdout, stderr) => {
-      if (error) reject(error);
-      else resolve(stdout);
-    });
-  });
-}
-
-analyzePerformance().catch(console.error);
-```
-
-## Best Practices
-
-### 1. Regular Analysis
-- Run bottleneck detection after major changes
-- Generate weekly performance reports
-- Monitor trends over time
-- Set up automated alerts
-
-### 2. Threshold Tuning
-- Start with default threshold (20%)
-- Lower for production systems (10-15%)
-- Higher for development (25-30%)
-- Adjust based on requirements
-
-### 3. Fix Strategy
-- Always review before applying --fix
-- Test fixes in development first
-- Apply fixes incrementally
-- Monitor impact after changes
-
-### 4. Report Integration
-- Include in documentation
-- Share with team regularly
-- Track improvements over time
-- Use for capacity planning
-
-### 5. Continuous Optimization
-- Learn from each analysis
-- Build performance budgets
-- Establish baselines
-- Set improvement goals
-
-## Troubleshooting
-
-### Common Issues
-
-**High Memory Usage**
-```bash
-# Analyze memory bottlenecks
-npx monomind bottleneck detect --threshold 10
-
-# Check cache performance
-npx monomind cache manage --action stats
-
-# Review memory metrics
-npx monomind memory usage
-```
-
-**Slow Task Execution**
-```bash
-# Identify slow tasks
-npx monomind task status --detailed
-
-# Analyze coordination overhead
-npx monomind bottleneck detect --time-range 1h
-
-# Check agent utilization
-npx monomind agent metrics
-```
-
-**Poor Cache Performance**
-```bash
-# Analyze cache hit rates
-npx monomind analysis performance-report --sections metrics
-
-# Review cache strategy
-npx monomind cache manage --action analyze
-
-# Enable cache warming
-npx monomind bottleneck detect --fix
-```
-
-## Integration with Other Skills
-
-- **swarm-orchestration**: Use performance data to optimize topology
-- **memory-management**: Improve cache strategies based on analysis
-- **task-coordination**: Adjust scheduling based on bottlenecks
-- **neural-training**: Train patterns from performance data
-
-## Related Commands
-
-- `npx monomind swarm monitor` - Real-time monitoring
-- `npx monomind token usage` - Token optimization analysis
-- `npx monomind cache manage` - Cache optimization
-- `npx monomind agent metrics` - Agent performance metrics
-- `npx monomind task status` - Task execution analysis
-
-## See Also
-
-- [Bottleneck Detection Guide](https://github.com/monoes/monomind/wiki/bottleneck-detect)
-- [Performance Report Guide](https://github.com/monoes/monomind/wiki/performance-report)
-- [Performance Bottlenecks Overview](https://github.com/monoes/monomind/wiki/performance-bottlenecks)
-- [Swarm Monitoring Documentation](../swarm-orchestration/SKILL.md)
-- [Memory Management Documentation](../memory-management/SKILL.md)
-
----
-
-**Version**: 1.0.0
-**Last Updated**: 2025-10-19
-**Maintainer**: Monomind Team