---
name: perf-audit
description: Use when auditing performance — baseline, profile, identify top 3 bottlenecks, fix, remeasure
arguments:
  - name: target
    description: "What to audit: endpoint, page, function, or 'full'"
    required: true
---

# Performance Audit Workflow

## When to use

- Auditing an API endpoint, page, or function for performance regressions (baseline → profile → fix → remeasure).
- Identifying the top 3 bottlenecks (DB N+1, sequential network calls, CPU hotspots, bundle bloat).
- Before shipping a feature that touches a known hot path and needs measured before/after numbers.

## Step 1: Establish Baseline
- Measure current performance:
  - API: response time (p50, p95, p99), throughput
  - Frontend: LCP, FID, CLS, bundle size
  - Function: execution time, memory usage
- Record numbers BEFORE any changes
- Use project's existing tools or:
  - Python: `time`, `cProfile`, `memory_profiler`
  - JS/TS: `performance.now()`, Lighthouse, `webpack-bundle-analyzer`
  - API: `curl -w @-` timing, `ab`, `wrk`

## Step 2: Profile
- Identify WHERE time is spent:
  - Database queries (N+1, missing indexes, full scans)
  - Network calls (sequential vs parallel, caching)
  - CPU (algorithmic complexity, unnecessary computation)
  - Memory (leaks, large allocations, unnecessary copies)
  - I/O (file reads, disk writes)

## Step 3: Identify Top 3 Bottlenecks
- Rank by impact (% of total time)
- Focus on top 3 — don't optimize everything
- For each: document what, why slow, potential fix

## Step 4: Checkpoint
- `checkpoint: before perf-audit $target`

## Step 5: Fix (One at a Time)
- Fix #1 bottleneck → measure → confirm improvement
- Fix #2 bottleneck → measure → confirm improvement
- Fix #3 bottleneck → measure → confirm improvement
- After each fix: run tests — no regressions

## Step 6: Final Measurement
- Re-run baseline measurements
- Compare before/after
- Report: metric, before, after, improvement %

## Step 7: Commit
- `perf: optimize $target — <summary of improvements>`