Profile-first performance investigation runbook — reproduce and baseline a metric, pick a profiler from the ecosystem tooling matrix (Go/Python/JVM/Node/Rust/Ruby/.NET/native), capture CPU + alloc profiles under load, hand the profile to the performance-tuner agent for ranked hotspot read, classify by bottleneck taxonomy (CPU/memory-GC/I-O/lock-contention), form one hypothesis, make one isolated change, before/after measurement, regression guard. Keywords: profile flame graph hotspot bottleneck slow endpoint investigation benchmark.
Profile-first performance investigation runbook — reproduce and baseline a metric, pick a profiler from the ecosystem tooling matrix (Go/Python/JVM/Node/Rust/Ruby/.NET/native), capture CPU + alloc profiles under load, hand the profile to the performance-tuner agent for ranked hotspot read, classify by bottleneck taxonomy (CPU/memory-GC/I-O/lock-contention), form one hypothesis, make one isolated change, before/after measurement, regression guard. Keywords: profile flame graph hotspot bottleneck slow endpoint investigation benchmark.
You already have a profile and only need the ranked hotspot read → invoke the performance-tuner agent directly via /swe-workbench:review --mode perf.
Reviewing a PR diff for perf regressions → /swe-workbench:review --mode perf.
Composition
swe-workbench:principle-performance — design-time discipline (Big-O, allocation, N+1, data locality). Run inline or hand off; never skip the discipline layer.
performance-tuner agent — ranked hotspot analysis given a captured profile. Hand the profile artifact at Phase 3; do not invoke before a profile exists.
swe-workbench:observability-context — production signal framing at Phase 1 only (a Sentry error rate, regression, or alert that motivated this investigation). Never invoke it at Phase 3 or later, and never let its output substitute for the profile artifact performance-tuner requires — see the Evidence-class caveat in Phase 1 below.
Phases
Phase 1 — Frame & baseline
If a Sentry reference or production-alert signal motivated this investigation, invoke swe-workbench:observability-context and prepend its ## Observability context block here, at Phase 1 only. Evidence-class caveat: that block always carries **Evidence class:** production signal (Phase-1 framing) — NOT a profile; use it only to frame which endpoint/job to target — it never substitutes for the profile artifact Phase 2/3 require.
Reproduce the slowness reliably under a controlled load (script or benchmark).
Pick one metric: p99 latency, allocation rate, or throughput.
Record the baseline number before touching any code.
Phase 2 — Profile
Select the profiler from the tooling matrix below for the target ecosystem.
Capture a CPU profile and an alloc/heap profile under the same load as Phase 1.
Save the profile artifact (pprof file, flamegraph SVG, etc.) for Phase 3.
Phase 3 — Rank hotspots
Hand the profile artifact to the performance-tuner agent (/swe-workbench:review --mode perf) for ranked hotspot read.
Classify each hotspot by bottleneck taxonomy: CPU-bound · memory/GC · I/O · lock-contention.
Surface the top 3 ranked hotspots with their taxonomy label before hypothesizing.
Phase 4 — Hypothesize & isolate
Pick the #1 hotspot. Form one hypothesis (e.g., "this allocates per-request; pool it").
Make one isolated change. No bundled edits — mixed changes make before/after ambiguous.
Phase 5 — Measure before/after
Re-run the same profile + same metric from Phase 1 under identical load.
Keep the change only if it moves the baseline number in the right direction.
If no improvement: revert, revisit Phase 4 with the next hotspot.
Phase 6 — Verify & regression guard
Lock the win behind a benchmark or perf regression test (e.g., go test -bench, criterion, k6).
Confirm no regressions in adjacent paths by re-running the full benchmark suite.
Document the before/after numbers in the PR description.
