Performance Optimization

Performance Optimization

Use this skill when the main question is "what artifact do we trust, where is the actual bottleneck, and what is the smallest tuning move worth trying first?"

The job is not to dump generic React, SQL, caching, or game-performance tips. The job is to classify the complaint, normalize the current artifact into one tuning brief, pick one primary mode, name one bottleneck, recommend one or two high-leverage changes, then verify before/after impact and route remaining work correctly.

Read references/intake-packets-and-escalations.md before handling an unfamiliar artifact packet. Read references/tuning-modes.md before handling an unfamiliar performance complaint. Read references/handoff-boundaries.md when deciding whether performance-optimization, monitoring-observability, debugging, testing-strategies, code-refactoring, or game-performance-profiler should own the next step. Read references/measurement-checklist.md before writing a benchmark or profiling plan.

When to use this skill

• Slow interactions, page loads, route transitions, API hot paths, query plans, memory growth, bundle regressions, or frame-budget complaints where the bottleneck is not yet isolated
• Performance packets that arrive as traces, Lighthouse/CWV reports, flamegraphs, query plans, load-test diffs, profiler screenshots, benchmark notes, or stakeholder dashboards
• Cross-domain performance asks spanning CLI/dev workflow, web/fullstack, product/ops, marketing/content performance, or game-adjacent routing where the next owner is still unclear
• Situations where you need one bounded tuning brief instead of a generic performance tip dump

When not to use this skill

• The main task is rolling out dashboards, alerts, metrics, traces, or log pipelines → use monitoring-observability
• The main task is reproducing a correctness bug, isolating a regression, or understanding why behavior is wrong → use debugging
• The main task is safe structural cleanup, decomposition, or codemod planning without performance evidence → use code-refactoring
• The main task is choosing org-wide test layers, merge/release gates, or benchmark policy → use testing-strategies
• The bottleneck is clearly inside a Unity/Unreal/Godot capture and engine-specific interpretation is the main job → use game-performance-profiler
• The bottleneck is already isolated and the next task is stack-specific implementation detail; route to the implementation skill after framing the tuning brief

Instructions

Step 1: Frame the complaint

Capture the smallest useful statement of the problem before prescribing fixes.

Record:

• surface: CLI/dev | frontend/page-load | API/service | database | async/capacity | report/dashboard | runtime/game | unknown
• symptom: high latency | low throughput | memory growth | CPU saturation | slow query | large bundle | weak CWV | frame spike | unknown
• decision target: p50/p95/p99 latency, throughput, bundle size, memory ceiling, frame budget, CWV metric, or benchmark duration
• environment: local | CI benchmark | staging | production | target device/hardware | mixed/unknown
• whether this is a regression, chronic hotspot, or vague complaint

Quick frame:

Surface: API + database
Symptom: p95 latency jumped from 180ms to 850ms on order search
Decision target: restore p95 < 250ms
Environment: production-like staging
Regression: yes, after filter expansion

Step 2: Start from the intake packet

Use references/intake-packets-and-escalations.md.

Choose the packet the user actually has now:

• browser trace / DevTools recording
• Lighthouse, WebPageTest, or CWV report
• APM trace, flamegraph, profiler output, or benchmark diff
• EXPLAIN / query-plan / slow-query artifact
• profiler screenshot / stat overlay / engine capture
• spreadsheet, dashboard, report summary, or no usable artifact yet

Output this step as:

## Intake Packet
- Current artifact:
- Why it is enough (or not enough):
- Missing context to collect next:

Rule: do not force users into an ideal measurement flow if the current artifact already narrows the next decision.

Step 3: Choose one primary tuning mode

Pick one primary mode from references/tuning-modes.md.

Primary modes:

• interaction-and-rendering
• page-load-and-bundle
• api-latency-and-hot-paths
• database-plan-and-data-access
• throughput-and-capacity
• memory-and-allocation
• runtime-frame-budget
• unknown-needs-better-measurement

Rule: one primary mode, optional secondary mode. Do not mix every possible optimization axis into one answer.

Step 4: Name the bottleneck before proposing fixes

Translate the evidence into one bottleneck statement.

Good bottleneck statements:

• “The endpoint is CPU-bound inside JSON serialization after DB work already returned.”
• “The search query plan is doing a wide sort + filter because the composite index does not match the predicate.”
• “Interaction delay is dominated by one long task plus layout thrash in the results panel.”
• “Frame spikes line up with asset streaming bursts on target hardware.”
• “The CWV report shows LCP dominated by image payload and render-blocking script cost, not server latency.”

Avoid vague statements like “performance is bad overall.”

Step 5: Recommend one or two high-leverage changes

Prioritize the smallest credible move that attacks the named bottleneck directly.

Candidate moves by mode:

• interaction-and-rendering: reduce rerender scope, defer non-critical work, avoid layout thrash, virtualize heavy lists, cut synchronous main-thread work
• page-load-and-bundle: split routes/modules, reduce JS, optimize asset delivery, compress/resize images, trim third-party cost, cache aggressively
• api-latency-and-hot-paths: remove blocking work, cache expensive responses, reduce serialization cost, parallelize safe downstream calls, precompute heavy transforms
• database-plan-and-data-access: fix query shape, add/adjust indexes, remove N+1 access, push filters earlier, change pagination strategy, reduce row width
• throughput-and-capacity: tune concurrency limits, queue shape, worker pool size, connection pool size, batch size, or cache hit path
• memory-and-allocation: reduce churn, bound caches, reuse buffers/objects where appropriate, stream instead of buffering, shrink payloads
• runtime-frame-budget: reduce per-frame work, spread expensive tasks, lower draw/overdraw pressure, defer streaming bursts, simplify expensive effects
• unknown-needs-better-measurement: do not guess; ask for the cheapest artifact that can separate likely causes

Rule of thumb: recommend at most two candidate changes unless the next move is gathering better evidence.

Step 6: State tradeoffs and route-outs

Every tuning suggestion should include what could get worse.

Examples:

• caching may improve latency but increase staleness or memory pressure
• batching may improve throughput but hurt tail latency
• pagination/index changes may speed one query while complicating writes
• lazy loading or splitting may improve initial load but increase later interaction latency
• image compression or asset simplification may reduce quality or require content/design signoff

Route implementation when needed:

• component/state architecture cleanup → react-best-practices, state-management, or ui-component-patterns
• schema/index/data-model redesign → database-schema-design
• telemetry rollout or ongoing alerting → monitoring-observability
• benchmark-gate policy → testing-strategies
• engine-specific profiler interpretation → game-performance-profiler
• correctness-first reproduction or environment drift → debugging

Step 7: Verify before/after impact

Use references/measurement-checklist.md.

Verification packet should include:

• baseline metric and environment
• changed variable(s)
• after metric under comparable conditions
• whether the main bottleneck moved or disappeared
• residual risk / follow-up measurement

Good verification brief:

Baseline: p95 search latency 850ms on staging replay dataset
Change: added `(team_id, status, created_at)` index and removed N+1 author lookup
After: p95 230ms, DB time down 68%, CPU flat
Residual risk: cache-miss path still spikes at 400ms for very wide date ranges
Next if needed: cap date window or async export path

Output format

## Performance Brief
- Surface:
- Symptom:
- Decision target:
- Primary mode:
- Current artifact:

## Bottleneck Hypothesis
- Primary bottleneck:
- Confidence:
- Why:

## Highest-Leverage Changes
1. ...
2. ...

## Tradeoffs / Risks
- ...

## Verification Plan
- Baseline:
- After:
- Guardrail:

## Route-outs
- ...

Examples

Example 1: API + DB latency regression

Input: “Our order search endpoint is suddenly slow after adding more filters. We have EXPLAIN ANALYZE output and slow query logs.”

Expected shape: classify as database-plan-and-data-access with an API secondary mode, use the current artifacts instead of asking for generic telemetry first, isolate the hottest query or serialization layer, propose one or two targeted changes, then define before/after verification.

Example 2: Marketing / content performance report

Input: “Our landing-page CWV report shows poor LCP and INP. We have Lighthouse and field data but not a profiler trace yet.”

Expected shape: classify as page-load-and-bundle, treat the report as a real intake packet, separate likely asset/render-blocking causes from telemetry gaps, recommend one or two bounded next moves, and note when additional traces would be worth collecting.

Example 3: Route-out to observability setup

Input: “We need dashboards, traces, and alerts so we can catch slow endpoints before users complain.”

Expected shape: route to monitoring-observability instead of pretending the main task is already optimization.

Example 4: Route-out to game engine profiler skill

Input: “Unreal is hitching on Steam Deck and I have an Insights capture. Can you help interpret it?”

Expected shape: acknowledge the broader performance context but route engine-specific capture interpretation to game-performance-profiler.

Best practices

1. Start from the artifact the user already has; normalize it into a tuning brief instead of discarding it. 2. Measure first, then tune. 3. Name one primary bottleneck before prescribing changes. 4. Keep recommendations bounded: one or two high-leverage moves beat a giant checklist. 5. Compare like-for-like environments when verifying impact. 6. Be explicit about tradeoffs, especially cache, consistency, memory, and content-quality costs. 7. Route telemetry setup, debugging, refactoring, and engine-specific profiler reading to neighboring skills instead of absorbing everything.

References

• Chrome DevTools Performance
• Lighthouse overview
• Core Web Vitals
• PostgreSQL EXPLAIN
• pg_stat_statements
• Flame Graphs
• Unity Profiler
• Unreal Insights
• Godot Profiler

Handoff Boundaries

Use performance-optimization only when the core task is measurement-led tuning.

Route to monitoring-observability

Use monitoring-observability when the unanswered question is:

• which metrics, traces, logs, dashboards, or alerts should exist
• how to instrument the service or app
• how to roll out observability platforms, exporters, or alert rules
• how to make performance signals continuously visible

Rule of thumb: observability sets up the telemetry. performance-optimization consumes that telemetry to choose a tuning move.

Route to debugging

Use debugging when the unanswered question is:

• why the behavior is incorrect
• which change caused the regression
• how to reproduce or isolate a correctness failure
• whether the issue is a bug first and a performance issue second

Rule of thumb: if expected behavior is still unclear, debug first.

Route to code-refactoring

Use code-refactoring when the unanswered question is:

• how to simplify or decompose a subsystem safely
• how to stage a cleanup or migration without changing behavior
• how to remove duplication or create reviewable slices
• whether the work is maintainability-driven rather than performance-driven

Rule of thumb: if performance evidence is not the reason for the change, it is not performance optimization yet.

Route to testing-strategies

Use testing-strategies when the unanswered question is:

• which benchmarks or test layers should be merge-gating or release-gating
• how much validation depth is required across the org or repo
• what the benchmark/perf regression policy should be
• how to handle flaky or expensive performance suites at policy level

Rule of thumb: performance-optimization chooses enough verification for one bottleneck. testing-strategies designs the lasting policy.

Route to game-performance-profiler

Use game-performance-profiler when the unanswered question is:

• how to interpret Unity Profiler or Unreal Insights captures
• whether a game/runtime issue is CPU, GPU, memory, streaming, or platform specific
• what profiling artifact to capture next for a game target
• how Steam Deck / console / mobile / VR constraints shape the diagnosis

Rule of thumb: performance-optimization can classify the broader problem, but engine-specific capture interpretation belongs there.

Route to implementation skills

Use stack-specific implementation skills when the bottleneck is already isolated and the next step is mainly doing the change:

• database-schema-design for schema/index/data-model design
• react-best-practices, state-management, or ui-component-patterns for frontend structural implementation
• workflow-automation when the main work is CI/job automation rather than performance reasoning

Intake Packets and Escalations

Start from the artifact the user already has. Do not throw it away just because a different tool would be ideal.

Browser trace / DevTools recording

Use when the complaint is sluggish clicks, filter changes, scrolling, layout thrash, or slow route interactions.

Look for:

• long tasks
• rerender fan-out
• layout/style recalculation cost
• scripting bursts before paint
• network waterfalls tied to interaction

Escalate when:

• the trace points to framework/component structure work → react-best-practices, state-management, or ui-component-patterns
• the trace is only a symptom and backend latency dominates → stay in performance-optimization and switch modes

Lighthouse / WebPageTest / CWV report

Use when the complaint is poor LCP/INP/CLS, weak landing-page speed, or stakeholder-facing page-performance review.

Look for:

• large image or font payloads
• render-blocking CSS/JS
• third-party script cost
• weak cacheability
• clear server-vs-client split

Escalate when:

• the ask is ongoing telemetry, dashboards, or field-data rollout → monitoring-observability
• the next work is content/design/system implementation rather than bottleneck reasoning → route after naming the bottleneck

APM trace / flamegraph / runtime profiler

Use when the complaint is endpoint latency, CPU hot paths, serialization cost, or runtime overhead.

Look for:

• one expensive function or span
• downstream call fan-out
• serialization/deserialization cost
• lock contention or blocking I/O
• repeated work inside the hot path

Escalate when:

• the root issue is correctness or regression isolation first → debugging
• the bottleneck is already isolated and the next work is implementation-specific

Query plan / slow-query artifact

Use when SQL or ORM behavior is the main suspect.

Look for:

• missing or mismatched indexes
• wide sorts / joins / scans
• bad row estimates
• N+1 access patterns
• pagination or row-width issues

Escalate when:

• the next task is schema/index/data-model redesign → database-schema-design
• the query is only one symptom of a broader incident and reproduction is still unclear → debugging

Load-test comparison / benchmark diff

Use when the complaint is throughput, queue growth, worker saturation, or a regression across runs.

Look for:

• changed saturation point
• queue-depth growth
• concurrency or connection-pool pressure
• one endpoint dominating errors/latency
• whether the comparison is trustworthy across the same workload

Escalate when:

• the ask is benchmark policy / gating across the repo or org → testing-strategies
• the evidence is too noisy to support a concrete bottleneck statement

Profiler screenshot / stat overlay / engine capture

Use when the complaint is frame spikes, low FPS, platform-specific hitching, or runtime streaming cost.

Look for:

• CPU vs GPU vs memory pressure
• frame-budget overruns
• streaming bursts or asset spikes
• target-device differences
• whether the artifact is enough to classify the bottleneck before engine-specific interpretation

Escalate when:

• the main job is Unity/Unreal/Godot capture interpretation → game-performance-profiler
• there is no real capture yet and the next step is deciding what to record on target hardware

Spreadsheet / dashboard / report summary

Use when marketing, growth, product, or ops stakeholders bring a report instead of a profiler artifact.

Look for:

• repeated weak metrics by page/cohort/device
• whether the report already separates field vs lab data
• obvious asset, render-blocking, or backend symptoms
• whether the ask is a stakeholder summary or a tuning brief

Escalate when:

• the real job is report production / dashboard design rather than optimization → another reporting/analytics skill
• the report only proves a symptom and the next step is collecting a better engineering artifact

No usable artifact yet

Use unknown-needs-better-measurement when the complaint is too vague to justify a tuning move.

Ask for the cheapest artifact that can separate likely causes:

• browser trace for interaction slowness
• Lighthouse or CWV report for page-load complaints
• APM trace / flamegraph for endpoint CPU issues
• EXPLAIN / slow-query data for SQL complaints
• benchmark comparison for throughput/regression claims
• target-device capture for frame-budget issues

Measurement Checklist

Use this checklist before claiming a win.

Baseline

• What exact metric matters? (p95 latency, bundle size, frame time, memory ceiling, throughput)
• What environment produced the number? (local, staging replay, prod trace, target hardware)
• What workload or scenario was used?
• Is the metric stable enough to compare, or is more sampling needed?

Evidence quality

• Primary artifact captured: trace, flame graph, query plan, heap/alloc profile, load-test output, frame capture
• Why this artifact is enough for the current decision
• Known blind spots or confounders

Proposed change

• One or two changes only
• Explicit expected effect on the chosen metric
• Known tradeoffs: cache freshness, memory growth, complexity, write amplification, visual quality, etc.

Verification

• Same workload or close equivalent as baseline
• Before/after numbers written together
• Check whether the bottleneck moved somewhere else
• Note residual risk or next measurement if the problem is only partially solved

Example

Metric: p95 search latency
Environment: staging replay with production-like dataset
Baseline: 850ms
Artifact: EXPLAIN ANALYZE + APM trace
Change: composite index + remove N+1 author fetch
After: 230ms
Tradeoff: slightly slower writes on order update path
Residual risk: very wide date-range queries still spike

Tuning Modes

Use one primary mode per request. Add a secondary mode only when the evidence clearly spans layers.

interaction-and-rendering

Use when the complaint is about sluggish clicks, filter changes, scrolling, layout thrash, or heavy rerenders.

Look for:

• long tasks
• rerender fan-out
• layout / style recalculation cost
• expensive client-side transforms
• main-thread work that blocks input handling

page-load-and-bundle

Use when the complaint is about first paint, LCP, oversized bundles, or request waterfalls.

Look for:

• large JS/CSS/image payloads
• render-blocking resources
• bad cacheability
• third-party script cost
• route/module split opportunities

api-latency-and-hot-paths

Use when one endpoint, job, or code path is slow even after the workload is known.

Look for:

• CPU-heavy transforms
• serialization cost
• blocking I/O
• slow downstream dependencies
• duplicated work inside the request path

database-plan-and-data-access

Use when SQL/ORM behavior is the main suspect.

Look for:

• missing or mismatched indexes
• N+1 access patterns
• bad join/order/filter plans
• too many rows read before filtering
• pagination or row-width issues

throughput-and-capacity

Use when the complaint is saturation under load rather than one slow request.

Look for:

• queue depth growth
• worker-pool saturation
• connection-pool contention
• lock contention
• rate-limit or concurrency mismatches

memory-and-allocation

Use when the issue is memory growth, allocation churn, or GC pressure.

Look for:

• cache cardinality growth
• temporary object churn
• buffering large payloads
• leaks or forgotten lifetimes
• repeated parsing/serialization work

runtime-frame-budget

Use when the issue is frame-time spikes, low FPS, or target-device/runtime performance.

Look for:

• per-frame CPU spikes
• GPU pressure
• asset streaming bursts
• draw-call/overdraw problems
• device-specific thermal or platform constraints

unknown-needs-better-measurement

Use when the complaint is vague and the existing evidence does not yet justify a tuning move.

Recommended output:

• what to capture next
• why that artifact is the first one
• what decision it will unlock