performance-triage-and-bottleneck-hunting

Performance Triage And Bottleneck Hunting

Use this skill when the real problem is finding the bottleneck, not prematurely applying optimizations.

Scope

• slow pages, routes, interactions, and API endpoints
• unclear ownership between network, server, database, render, and bundle cost
• deciding whether performance work belongs to Next.js, React, Node.js, or infrastructure
• turning vague “this feels slow” reports into measurable bottlenecks

Routing cues

• slow route, slow page load, high TTFB, bad interaction latency, render lag, hydration cost, p95 regression, or “where is the bottleneck” -> use this skill
• once the dominant cost is clearly React rerenders or state blast radius -> use react-render-performance-and-state-boundaries
• once the dominant cost is clearly Next.js route rendering, bundle, or client boundary cost -> use nextjs-performance-and-render-cost
• once the dominant cost is clearly API latency or server throughput -> use nodejs-api-latency-and-throughput
• once the bottleneck is already known and the task is measurement discipline -> use profiling-before-optimizing

Default path

1. Restate the user-visible symptom in one sentence.
2. Choose one primary metric that represents the pain:
   • route TTFB
   • interaction latency
   • slow API duration
   • render or hydration time
   • memory growth or CPU saturation
3. Identify the likely owning layer before editing code:
   • network and third-party
   • server and database
   • React render tree
   • client bundle and hydration
4. Measure one representative path end to end.
5. Name the dominant bottleneck and only then route to the narrower optimization skill.

When to deviate

• Use synthetic benchmarks only when the real user path is unavailable or too noisy.
• Start with production telemetry when it already exists and the local reproduction is misleading.
• Split into multiple bottlenecks only when one path truly has more than one dominant cost center.

Guardrails