afrexai-performance-engineering

# Performance Engineering System

> From "it's slow" to "here's why and here's the fix" — a complete methodology for measuring, diagnosing, optimizing, and preventing performance problems.

## Phase 1: Performance Investigation Brief

Before touching anything, define the problem.

```yaml
# performance-brief.yaml
investigation:
  reported_by: ""
  reported_date: ""
  system: ""              # service/app name
  environment: ""         # production, staging, dev

problem_statement:
  symptom: ""             # "API response time increased 3x"
  impact: ""              # "15% of users seeing timeouts"
  since_when: ""          # "After deploy v2.14 on Feb 20"
  affected_scope: ""      # "All endpoints" | "Only /search" | "Users in EU"

baselines:
  target_p50: ""          # e.g., "200ms"
  target_p95: ""          # e.g., "500ms"
  target_p99: ""          # e.g., "1000ms"
  current_p50: ""
  current_p95: ""
  current_p99: ""
  throughput_target: ""   # e.g., "1000 rps"
  error_rate_target: ""   # e.g., "<0.1%"

constraints:
  budget: ""              # time/money for optimization
  risk_tolerance: ""      # "Can we change the schema?" "Can we add caching?"
  deadline: ""            # "Must fix before Black Friday"

hypothesis:
  primary: ""             # "N+1 queries in the new recommendation engine"
  secondary: ""           # "Connection pool exhaustion under load"
  evidence: ""            # "Slow query log shows 200+ queries per request"
```

### Performance Budget Framework

Set budgets BEFORE building, not after complaints:

| Metric | Web App | API | Mobile | Batch Job |
|--------|---------|-----|--------|-----------|
| P50 response | <200ms | <100ms | <300ms | N/A |
| P95 response | <500ms | <250ms | <800ms | N/A |
| P99 response | <1s | <500ms | <1.5s | N/A |
| Error rate | <0.1% | <0.01% | <0.5% | <0.001% |
| Time to Interactive | <3s | N/A | <2s | N/A |
| Memory per request | <50MB | <20MB | <100MB | <1GB |
| CPU per request | <100ms | <50ms | <200ms | N/A |
|...

# AfrexAI Performance Engineering 🖤💛

Complete performance engineering system for your AI agent — from "it's slow" to "here's why and here's the fix."

## What This Skill Does

Turns your agent into a performance engineering expert that can:

- **Diagnose** slow applications with structured investigation briefs
- **Profile** CPU, memory, and I/O across Node.js, Python, Go, and Java
- **Optimize** algorithms, queries, caching, and concurrency patterns
- **Load test** APIs with k6 templates and results interpretation
- **Plan capacity** with growth projections and cost-performance analysis
- **Prevent regressions** with CI/CD performance gates
- **Score** your system's performance maturity (0-100)

## Install

```bash
clawhub install afrexai-performance-engineering
```

## Quick Start

Tell your agent:
- "Why is this endpoint slow?" → Full investigation + profiling
- "Load test the API" → k6 test design and execution
- "Optimize this query" → EXPLAIN ANALYZE + index recommendations
- "Score our performance" → 100-point maturity assessment

## What's Inside

- **Performance Budget Framework** — target metrics by app type
- **Profiling Decision Tree** — CPU, I/O, memory, or concurrency?
- **Language-specific profilers** — Node.js, Python, Go, Java with code examples
- **Flame graph interpretation** — what to look for, action rules
- **Optimization patterns** — algorithm fixes, caching matrix, N+1 detection, connection pools
- **Database performance** — EXPLAIN ANALYZE guide, index strategy, query checklist
- **Load testing** — k6 templates, results analysis, bottleneck identification
- **Frontend performance** — Core Web Vitals fixes, bundle optimization
- **Capacity planning** — growth models, cost-performance ROI calculation
- **CI/CD gates** — automated regression detection
- **100-point scoring rubric** — measurement, prevention, optimization, operations

## ⚡ Level Up

This skill covers the methodology. For industry-specific performance patterns and production a...