perf-ops

What this skill does

# Performance Operations

Orchestrator for cross-language performance profiling and optimization. Classifies symptoms inline, dispatches profiling to language expert agents (background), and manages optimization with confirmation.

## Architecture

```
User describes performance issue or requests profiling
    |
    +---> T1: Diagnose (inline, fast)
    |       +---> Classify symptom (decision tree)
    |       +---> Detect language/runtime from project
    |       +---> Check installed profiling tools
    |       +---> Determine production vs development
    |       +---> Gather system baseline (CPU/mem/disk)
    |       +---> Present: diagnosis + recommended profiling approach
    |
    +---> T2: Profile (dispatch to language expert, background)
    |       +---> Select expert agent from routing table
    |       +---> Build perf-focused dispatch prompt
    |       +---> Expert runs profiler, collects data, interprets results
    |       |       +---> Fallback: general-purpose with tool commands inlined
    |       +---> Returns: findings + bottleneck identification + suggestions
    |       |
    |       +---> [Optional parallel dispatch]:
    |             +---> CPU profiling agent  ---+
    |             +---> Memory profiling agent --+--> Consolidate findings
    |             +---> Baseline benchmark ------+
    |
    +---> T3: Optimize (dispatch to expert, foreground + confirm)
            +---> Expert proposes specific code changes
            +---> Preflight: what changes, expected impact, risks
            +---> User confirms
            +---> Apply changes
            +---> Re-benchmark for before/after delta
```

## Safety Tiers

### T1: Diagnose - Run Inline

No agent needed. Execute directly via Bash for instant results.

| Operation | Command / Method |
|-----------|-----------------|
| Detect Python profilers | `which py-spy && which memray && which scalene` |
| Detect Go profilers | `which go && go tool pprof -h 2>/dev/null` |
| Detect Rust profilers | `which cargo-flamegraph && which samply` |
| Detect Node profilers | `which clinic && which 0x` |
| Detect benchmarking tools | `which hyperfine && which k6 && which vegeta` |
| System CPU baseline | `top -bn1 -o %CPU \| head -20` (Linux) or `wmic cpu get loadpercentage` (Win) |
| System memory baseline | `free -h` (Linux) or `wmic OS get FreePhysicalMemory` (Win) |
| Disk I/O check | `iostat -x 1 3` (Linux) |
| Identify language | Check for `package.json`, `go.mod`, `Cargo.toml`, `pyproject.toml`, `requirements.txt` |
| Production vs dev | Ask user or detect from environment (NODE_ENV, FLASK_ENV, etc.) |
| Read existing profiles | Parse `.prof`, `.svg`, `.bin` files in project |

**Production safety rule:** In production environments, only recommend sampling profilers (py-spy, pprof HTTP endpoint, perf). Never suggest attaching debuggers, tracing profilers, or tools that require process restart.

### T2: Profile - Dispatch to Expert Agent

Gather context from T1 diagnosis, then dispatch to the appropriate language expert.

**Language Expert Routing:**

| Detected Language | Expert Agent | Key Profiling Tools |
|-------------------|-------------|---------------------|
| Python (.py, pyproject.toml, requirements.txt) | python-expert | py-spy, memray, scalene, tracemalloc |
| Go (go.mod, .go files) | go-expert | pprof (CPU/heap/goroutine/mutex), benchstat |
| Rust (Cargo.toml, .rs files) | rust-expert | cargo-flamegraph, samply, DHAT, criterion |
| TypeScript/JavaScript (backend, package.json + server) | javascript-expert | clinic flame/doctor/bubbleprof, 0x |
| TypeScript/JavaScript (frontend, bundle issues) | typescript-expert | webpack-bundle-analyzer, Lighthouse, source-map-explorer |
| SQL / PostgreSQL | postgres-expert | EXPLAIN ANALYZE, pg_stat_statements, pgbench |
| General / unknown / CLI benchmarking | general-purpose | hyperfine, perf, strace |

**Dispatch template (T2):**

```
You are handling a performance profiling task dispatched by the perf-ops orchestrator.

## Diagnosis (from T1)
- Symptom: {classified symptom from decision tree}
- Language/Runtime: {detected language}
- Environment: {production | development}
- Installed tools: {list from tool detection}
- System baseline: {CPU/memory/disk metrics}

## Profiling Task
{specific profiling request - e.g., "CPU profile the API server under load"}

## Target
- Process/file: {target application or endpoint}
- Expected workload: {how to generate representative load if needed}

## Domain Knowledge
Before starting, read the relevant profiling reference for this language:
- Read: skills/perf-ops/references/cpu-memory-profiling.md

For load testing tasks, also read:
- Read: skills/perf-ops/references/load-testing.md

For database profiling, also read:
- Read: skills/postgres-ops/SKILL.md (if PostgreSQL)

## Instructions
1. Run the appropriate profiler for this language and symptom
2. Collect sufficient samples (minimum 30 seconds for CPU, multiple snapshots for memory)
3. Interpret the results - identify the top 3-5 bottlenecks
4. For each bottleneck: explain what it is, why it's slow, and suggest a fix
5. Report findings in structured format with metrics
```

**Execution mode:**

| Scenario | Mode | Why |
|----------|------|-----|
| User waiting for results | `run_in_background=False` | They need findings before continuing |
| User continuing other work | `run_in_background=True` | Don't block the main session |
| Quick benchmark (hyperfine) | `run_in_background=False` | Fast enough to wait |
| Load test (k6, artillery) | `run_in_background=True` | Takes minutes |

### T3: Optimize - Preflight Required

Dispatch to language expert with explicit instruction to produce a preflight report before any code changes.

**Dispatch template (T3 preflight):**

```
You are handling a performance optimization dispatched by the perf-ops orchestrator.

## Profiling Results (from T2)
{bottleneck findings, metrics, flamegraph interpretation}

## Optimization Request
{specific optimization - e.g., "Fix the N+1 query in UserController.list"}

IMPORTANT: Do NOT apply changes yet. Produce a Preflight Report:
1. Exactly what code/config changes you will make
2. Expected performance improvement (with reasoning)
3. Risks (correctness, side effects, edge cases)
4. How to verify the improvement (specific benchmark or test)
5. How to revert if the optimization causes issues
```

**After user confirms:** Re-dispatch with execute authority plus the before/after protocol.

**Dispatch template (T3 execute + before/after):**

```
User confirmed the optimization. Proceed with execution.

## Approved Changes
{exact changes from preflight report}

## Before/After Protocol
1. Record the current benchmark baseline: {specific command from T2}
2. Apply the approved changes
3. Run the same benchmark again
4. Report comparison:
   - Metric: before value -> after value (% change)
   - Include statistical confidence if tool supports it
5. If regression detected: revert and report
```

## Parallel Profiling

When multiple independent symptoms are detected, or the user requests comprehensive profiling, dispatch parallel agents.

**Parallelizable combinations:**

| Agent 1 | Agent 2 | Why Independent |
|---------|---------|-----------------|
| CPU profiler | Memory profiler | Different tools, different data |
| CPU profiler | Baseline benchmark | Read vs measurement |
| Backend profiler | Frontend bundle analysis | Different runtimes |
| Service A profiler | Service B profiler | Different processes |

**NOT parallelizable:**

| Operation A | Operation B | Why Sequential |
|-------------|-------------|----------------|
| Profile | Interpret results | Dependency |
| Before benchmark | After benchmark | Requires code change between |
| Load test | CPU profile same process | Tool interference |

**Dispatch pattern for parallel profiling:**

```python
# Example: CPU + memory profiling in parallel
Agent(
    subagent_type="python-expert",
    model="sonnet",
    run_in_backg