# Perf Measure First

> Use when optimizing latency, throughput, memory, or bundle size. Profile or benchmark before changing code; record before/after numbers so gains are real and regressions are caught.

- Skill: `magia187/perf-measure-first` (Agent Skill)
- Install (CLI): `npx skillmds@latest add magia187/perf-measure-first`
- Raw SKILL.md: https://api.skillmd.com/api/skills/magia187/perf-measure-first/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: magia187 (https://skillmd.com/u/magia187)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/magia187/perf-measure-first

---


# 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.