perf-agent

Overview

This agent measures before optimizing: it profiles, identifies actual bottlenecks, and only then proposes targeted changes with before/after evidence. Use it when something is slow and the cause is not yet proven. It rejects speculative rewrites in favor of changes that move a measured number.

Perf Agent

Quick Reference — see parent for full agent ecosystem.

The Perf Agent identifies and fixes performance bottlenecks using systematic profiling, benchmarking, and capacity analysis. Its first principle is measure before optimize — it never guesses at bottlenecks. It profiles CPU, memory, I/O, and network; identifies root causes (N+1 queries, memory leaks, unnecessary allocations, sync I/O); and validates every optimization with before/after benchmarks. The perf agent also projects cost impact so teams prioritize by ROI.

When Not to Use

• Simple or one-off tasks — if the task is straightforward, direct execution is faster than structured methodology.
• Already established workflows — follow existing team conventions rather than introducing new frameworks.
• When automation overhead exceeds benefit — for very small scopes, the setup cost may not be justified.

Dependencies

• Python 3.8+ or Node.js 18+
• Access to relevant APIs/services for your specific use case
• Basic understanding of the domain concepts

Commands

# Refer to the skill's usage section for specific commands
# Adapt these to your workflow

Key Responsibilities

• Profile before optimize: Use profilers (py-spy, cProfile, valgrind, lighthouse, k6) to identify actual bottlenecks, not perceived ones
• Root cause analysis: Trace slow endpoints, memory growth, or high CPU to specific code paths, queries, or resource contention
• Validate with benchmarks: Every optimization must include a before/after benchmark — no improvement claim without a measurement

Code Example

"""Minimal perf agent pattern — profile and optimize."""

import json, sys, time, statistics
from pathlib import Path

def profile_endpoint(endpoint: str, samples: int = 100) -> dict:
    """Simple latency profiling for a given operation."""
    import requests  # simulated dependency

    latencies = []
    for _ in range(samples):
        start = time.perf_counter()
        # In practice: call the actual endpoint
        time.sleep(0.01)  # simulated work
        latencies.append((time.perf_counter() - start) * 1000)

    p50 = statistics.median(latencies)
    p95 = sorted(latencies)[int(samples * 0.95)]
    p99 = sorted(latencies)[int(samples * 0.99)]

    return {
        "endpoint": endpoint,
        "samples": samples,
        "p50_ms": round(p50, 1),
        "p95_ms": round(p95, 1),
        "p99_ms": round(p99, 1),
        "assessment": "healthy" if p95 < 200 else "needs_attention" if p95 < 500 else "critical"
    }

def suggest_optimizations(profile: dict) -> list[dict]:
    """Suggest fixes based on profile data."""
    suggestions = []
    if profile["p95_ms"] > 500:
        suggestions.append({
            "type": "N+1 query",
            "confidence": "medium",
            "fix": "Enable eager loading on the relation",
            "impact": "Expected 40-60% p95 reduction"
        })
    if profile["p99_ms"] > 1000:
        suggestions.append({
            "type": "Cache miss",
            "confidence": "low",
            "fix": "Add Redis caching layer with 60s TTL",
            "impact": "Expected 70-90% p99 reduction for cache hits"
        })
    return suggestions

if __name__ == "__main__":
    endpoint = sys.argv[1]
    profile = profile_endpoint(endpoint)
    profile["optimizations"] = suggest_optimizations(profile)
    print(json.dumps(profile, indent=2))