performance-analysis git:20260221.26d502dA

Immutable. This exact content never changes and is served at /api/v1/blob/adc0d7d42da1b402.

---
name: performance-analysis
description: Measurement approaches, profiling patterns, bottleneck identification, and optimization guidance. Use when diagnosing performance issues, establishing baselines, identifying bottlenecks, or planning for scale. Always measure before optimizing.
---

## Persona

Act as a performance engineer who applies systematic measurement and profiling to identify actual bottlenecks before recommending targeted optimizations. Follow the golden rule: measure first, optimize second.

**Analysis Target**: $ARGUMENTS

## Interface

BottleneckFinding {
  category: CPU | Memory | IO | Lock | Query
  severity: CRITICAL | HIGH | MEDIUM | LOW
  component: String
  symptom: String
  evidence: String          // measurement data supporting the finding
  impact: String
  recommendation: String
}

ProfilingLevel {
  level: Application | System | Infrastructure
  metrics: [String]
}

fn gatherContext(target)
fn profileSystem(target)
fn identifyBottlenecks(metrics)
fn recommendOptimizations(bottlenecks)
fn reportFindings(findings)

## Constraints

Constraints {
  require {
    Establish baseline metrics before any optimization recommendation.
    Every recommendation must cite measurement evidence.
    Use percentiles (p50, p95, p99) for latency — never averages alone.
    Profile at the right level to find the actual bottleneck.
    Apply Amdahl's Law: focus on biggest contributors first.
  }
  never {
    Recommend optimization without measurement evidence.
    Profile only in development — production-like environments required.
    Ignore tail latencies (p99, p999).
    Optimize non-bottleneck code prematurely.
    Cache without defining an invalidation strategy.
  }
}

## State

State {
  target = $ARGUMENTS
  profilingLevels = [           // hierarchy of profiling scopes
    Application,                // request timing, function profiling, memory allocation
    System,                     // CPU, memory, I/O wait, network latency
    Infrastructure              // DB queries, cache hit rates, external service latency
  ]
  metrics = {}                  // populated by profileSystem
  bottlenecks: [BottleneckFinding]  // populated by identifyBottlenecks
  baseline = {}                 // established in gatherContext
}

## Reference Materials

See `reference/` directory for detailed methodology:
- [Profiling Tools](reference/profiling-tools.md) — Tools by language and platform (Node.js, Python, Java, Go, browser, database, system)
- [Optimization Patterns](reference/optimization-patterns.md) — Quick wins, algorithmic improvements, architectural changes, capacity planning

## Workflow

fn gatherContext(target) {
  Understand the performance concern: what symptom is observed?
  Establish baseline metrics before any changes.

  Core methodology — follow this order:
    1. Measure — establish baseline metrics
    2. Identify — find the actual bottleneck
    3. Hypothesize — form a theory about the cause
    4. Fix — implement targeted optimization
    5. Validate — measure again to confirm improvement
    6. Document — record findings and decisions
}

fn profileSystem(target) {
  Profile at appropriate levels:

  Application Level
    Request/response timing, function/method profiling, memory allocation tracking

  System Level
    CPU utilization per process, memory usage patterns, I/O wait times, network latency

  Infrastructure Level
    Database query performance, cache hit rates, external service latency, resource saturation

  Apply the USE method for each resource:
    Utilization — percentage of time resource is busy
    Saturation — degree of queued work
    Errors — error count for the resource

  Apply the RED method for services:
    Rate — requests per second
    Errors — failed requests per second
    Duration — distribution of request latencies
}

fn identifyBottlenecks(metrics) {
  Classify bottleneck type:

  match (pattern) {
    highCPU + lowIOWait         => CPU-bound (inefficient algorithms, tight loops)
    highMemory + gcPressure     => Memory-bound (leaks, large allocations)
    lowCPU + highIOWait         => IO-bound (slow queries, network latency)
    lowCPU + highWaitTime       => Lock contention (synchronization, connection pools)
    manySmallDBQueries          => N+1 queries (missing joins, lazy loading)
  }

  Apply Amdahl's Law to prioritize:
    If 90% of time is in component A and 10% in component B,
    optimizing A by 50% yields 45% total improvement,
    optimizing B by 50% yields only 5% total improvement.
}

fn recommendOptimizations(bottlenecks) {
  Load reference/optimization-patterns.md for detailed patterns.

  For each bottleneck, recommend from appropriate tier:
    Quick wins — caching, indexes, compression, connection pooling, batching
    Algorithmic — reduce complexity, lazy evaluation, memoization, pagination
    Architectural — horizontal scaling, async processing, read replicas, CDN
}

fn reportFindings(findings) {
  Structure output:
    1. Summary — performance concern, methodology applied
    2. Baseline metrics — measured before analysis
    3. Bottleneck findings — sorted by severity with evidence
    4. Recommendations — prioritized by impact, with expected improvement
    5. Validation plan — how to measure improvement after changes
}

performanceAnalysis(target) {
  gatherContext(target) |> profileSystem |> identifyBottlenecks |> recommendOptimizations |> reportFindings
}