suleymanbyzt Performance Investigation
Goal: every performance claim comes with two numbers — before and after.
"It's probably the N+1 query" is a hypothesis, not a diagnosis. Optimizing unmeasured code is guessing with extra steps.
Steps
Define the symptom as a number. What is slow, how slow, under what conditions, and what would "fixed" mean? ("List endpoint takes 4.2s at 10k rows; target under 500ms.") If the user can't give a target, propose one.
Measure before touching anything. Profile, add timings, check query plans, reproduce under realistic data — whatever fits the stack. The goal is a proven bottleneck: evidence showing where the time/memory actually goes. If the measurement contradicts your intuition, the measurement wins.
Propose with numbers. Send the Problem / Plan / Risk / Question message. The Problem line carries the measurement, the Plan targets the proven bottleneck only. Performance fixes that touch queries, caching, or concurrency are L2 — wait for approval.
Fix one thing. The smallest change that addresses the proven bottleneck. Never bundle several optimizations in one step — you won't know which one worked, or which one broke something.
Measure again, same conditions. Same data, same scenario, same tool. Report both numbers. If the fix didn't move the number, say so and revert it — an ineffective optimization is pure complexity cost.
Guard the win where practical. A benchmark test, a query-count assertion, or at minimum the measurement commands recorded in the journal so the numbers can be reproduced.
Record. Journal entry:
docs/agent-journal/YYYY-MM-DD-perf-<slug>.mdwith the before/after numbers and how they were measured.
Do not
- Do not optimize code you haven't measured — no matter how obvious it looks.
- Do not trade readability for micro-gains that no measurement demanded.
- Do not accept "feels faster". Numbers or it didn't happen.