Performance Profiler

---
name: performance-profiler
description: |
  Trigger when the user asks to profile performance, find slow code, check
  p95 latency, or optimize a hot path. Phrases: "profile", "slow", "p95",
  "hot path", "optimize", "latency", "performance audit".
allowed-tools:
  - Read
  - Bash(node --prof *)
  - Bash(node --inspect *)
  - Grep
---

# Performance Profiler

Profile a Node web service or CLI and identify the hot path. Produce a
ranked list of fixes with estimated impact.

## Prerequisites

- Reproducible performance issue (slow route, slow CLI command)
- Node 18+ or modern runtime
- Load generator available (vegeta, k6, wrk) for server scenarios

## Steps

1. **Measure before changing anything.** Get p50, p95, p99 latency on the
   hot path under realistic load. Without numbers, any "optimization" is
   superstition.

2. **Profile the process.** For a Node server:

   ```bash
   node --prof ./server.js
   # run load
   node --prof-process isolate-*.log > profile.txt
   ```

   Or use clinic.js for flame graphs:

   ```bash
   npx clinic flame -- node ./server.js
   ```

3. **Identify the top 5 hot functions.** For each, ask:
   - Is it doing IO it does not need to? (N+1 queries, sync fs reads)
   - Is it allocating more than it needs to? (large object spreads in loops)
   - Is it running a polynomial-time operation on growing input?

4. **Apply the fix with the largest expected delta first.** Common wins:
   - N+1 query -> single JOIN or batched load
   - Sync fs or DNS inside request handler -> move to startup or cache
   - JSON.parse/stringify in hot path -> avoid round-tripping if possible
   - Recursive loops without memoization on growing input

5. **Measure again.** Confirm the delta matches the hypothesis. If not, the
   diagnosis was wrong; back out and reprofile.

## Anti-patterns

- Optimizing without a profile
- Micro-optimizing a function that is 1% of runtime
- Adding caches that introduce correctness bugs under concurrency
- Measuring on a debug build

## Output

- Before/after p50, p95, p99 numbers
- Flame graph or profile text attached
- PR with the fix; commit message cites the measured delta