git:20260710.7fdf9e2 to git:20260713.51dc745

2 added, 8 removed. Audit A to A.

---

name: performance

description: |

Stack-agnostic performance: measure first, find the bottleneck, then optimise. N+1, needless allocation, wrong

async boundary, missing index/cache, heavy payload. No premature optimisation.

Trigger phrases: "performance", "slow", "optimization", "profiling", "N+1", "latency", "memory leak", "load test"

---

# Performance

Core rule: **measure first, optimize later.** Optimization without measurement is a guess; it usually speeds up the

wrong place and adds complexity. Stack-agnostic; do a web search when you need the profiling tool/library.

## Method (in order)

1. **Set a target** — what is "acceptable"? (p95 latency, throughput, memory ceiling). Numeric.

2. **Measure** — find the real bottleneck with a profiler/APM/benchmark; don't start from a guess.

3. **Fix the single most expensive thing** — Amdahl: speeding up a 5% path by 2x is wasted; target the hot path.

4. **Measure again** — did it actually improve, is there a regression.

5. **Stop** — once you hit the target, finish; no endless micro-optimization.

## Common bottlenecks

- | Area | Pattern | Fix |

- |---|---|---|

- | **DB** | N+1 query, missing index, `SELECT *`, table scan | eager/batch loading, index (db-migration), only needed columns |

- | **Memory** | needless allocation, holding large objects, leak | pooling, streaming, releasing references |

- | **Async** | wrong sync/async boundary, blocking I/O, serial await | parallel await, non-blocking I/O |

- | **Network/payload** | oversized response, no compression, chatty API | pagination, field selection, gzip, batch (api-design) |

- | **Cache** | repeated expensive computation, no/wrong cache | cache at the right layer + correct invalidation |

- | **Frontend** | needless render, large bundle, blocking resource | memo, code-split, lazy, critical CSS |

+ Catalog of common bottlenecks + fixes to consult: **`references/bottlenecks.md`**.

## Measurement tips

- Measure **under load** (a single request misleads); with a realistic data volume.

- **Not p50, but p95/p99** — tail latency is what burns the user.

- Don't trust micro-benchmarks; an end-to-end profile is more honest.

## Invariant rules

1. **Don't optimize without measuring** — a change without a profile = a guess.

2. **Target the hot path** — don't speed up the small share.

3. **Don't break correctness** — don't sacrifice behavior/edge cases for speed.

4. **Complexity budget** — make an optimization that seriously hurts readability only if there is a measured gain; comment it.

5. **Stop once you hit the target** — YAGNI; no premature/excessive optimization.