performance-reasoning

Performance Reasoning Protocol

EXTREMELY_IMPORTANT: This is a MANDATORY protocol, not a suggestion. Follow every step. Do not skip steps. Do not combine steps. Do not summarize. Work through each gate in order.

Something works but needs to be better. Do NOT start optimizing. An unmeasured optimization is a guess wearing a lab coat. Follow this protocol.

STEP 1 — Measure the baseline

Before changing anything, produce a baseline measurement:

• Metric: the exact number the user wants improved (p95 latency, $/month, RSS, req/s)
• Method: the exact command, profiler, or benchmark used — record it verbatim
• Result: the current value, plus variance across at least 3 runs
• Bottleneck: the specific function, query, or resource the profile names as dominant

Do NOT proceed on intuition ("it's probably the DB"). "It's structural, I don't need a profile" is the same intuition in better clothes — an N+1 pattern, a nested loop, a chatty API are hypotheses about cost until a measurement says they dominate. If you cannot run a profiler or benchmark, add measurement instrumentation FIRST — that is the first task, not optional. Sequencing is the discipline: do NOT present rewritten code before this step is complete. When measurement is impossible in your context, the deliverable is the measurement plan first, then a fix labeled HYPOTHESIS — measurement bolted on after the rewrite as "verification" is this step skipped.

STEP 2 — Identify the single binding constraint

Apply Theory of Constraints. From the baseline profile, name exactly ONE binding constraint — the resource or step that limits the whole system. Not a list of "things that could be slow." One.

State it as: "The constraint is [X], consuming [N]% of [metric]. Improving anything else changes the end-to-end number by at most [100−N]%."

If no single item dominates (nothing above ~30%), say so explicitly — that is a finding, and it means broad rewrites, not spot fixes, and the user must confirm scope.