references/performance-method.md

# Evidence-first performance diagnosis

Ask which signal is slow or expensive and at what load: latency percentile, throughput, allocations, CPU, database time, memory, cost, distributed shuffle, model tokens.

Create a reproducible benchmark and capture a baseline. Profile hot paths and account for warm-up, caching, data shape, concurrency and hardware. Prioritize actual bottlenecks over superficial micro-optimizations.

Potential causes: repeated DB round trips, N+1 requests, unbounded queues, excessive payloads, blocking IO, large collection-to-driver, redundant model calls.

Compare before/after on representative workload; include correctness and regression tests. Report measurement conditions, variance and tradeoffs; do not invent measured speedups.