Perf Measure First

When to use

• The user asks to "make it faster", "reduce memory", or "optimize" a path.
• A performance regression is suspected after a change.
• You are about to rewrite hot code based on intuition alone.

When not to use

• Correctness bugs with no performance claim (fix first; optimize later).
• Micro-edits with no measurable user or system impact expected.
• Premature optimization on cold paths identified as non-critical.

Assumptions

• Ability to run a profiler, benchmark harness, or representative workload (e.g. hyperfine, language benchmarks, browser perf tools, clinic, pprof).
• A stable environment for comparison (same machine/flags when possible).
• Do not change production autoscaling, drop traffic, or alter live configs without confirmation.
• Do not commit large binary profiles or secrets from prod dumps without scrubbing and approval.

Workflow

1. Define the metric and success threshold (p95 latency, ops/sec, RSS, bundle KB).
2. Establish a reproducible benchmark or profile scenario.
3. Record a baseline (before) with command, environment, and numbers.
4. Change one hypothesized bottleneck at a time.
5. Record after; keep the change only if the metric improves without breaking tests.

Steps

1. Metric lock — Pick one primary metric and how it is measured. Avoid optimizing "feel" without numbers.
2. Scenario — Use production-like inputs/sizes; document dataset and command line.
3. Baseline — Run ≥3 iterations when noisy; save raw output or a short table in the PR.
4. Hypothesis — Name the suspected hotspot from the profile (function, query, alloc site) before editing.
5. Single-axis change — One optimization per experiment so attribution is clear.
6. Compare & guard — After numbers win, run functional tests; watch for accuracy/complexity regressions.

Success criteria

• Baseline numbers exist before optimization commits.
• After numbers use the same scenario/commands and show a clear delta.
• Changes map to a profile/benchmark-backed hypothesis.
• Functional tests still pass; no silent correctness tradeoff unless approved.
• Production-impacting knobs were confirmed or left untouched.

Out of scope

• Capacity planning and cluster-wide cost modeling.
• UX redesign unrelated to measured performance.
• Replacing the entire stack for a micro-gain without a business case.