ship-it-performance
Measure, diagnose, optimize, and verify user-visible performance across frontend, backend, API, database, job, and full-stack product flows. Use when an application feels slow, latency or throughput regresses, Core Web Vitals or bundle size miss targets, an endpoint or query is expensive, memory or CPU grows, load capacity is unknown, caching is being considered, or a release needs performance baselines and budgets. Establish a reproducible baseline, identify the highest-impact bottleneck with evidence, implement focused improvements, compare before and after under equivalent conditions, and add regression protection. Do not use for general feature work, visual redesign, standalone security review, cloud architecture, or cost optimization without a measured performance problem.
nanfei892 · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add nanfei892/ship-it-skills --skill ship-it-performanceAbout this skill
name: ship-it-performance description: "Measure, diagnose, optimize, and verify user-visible performance across frontend, backend, API, database, job, and full-stack product flows. Use when an application feels slow, latency or throughput regresses, Core Web Vitals or bundle size miss targets, an endpoint or query is expensive, memory or CPU grows, load capacity is unknown, caching is being considered, or a release needs performance baselines and budgets. Establish a reproducible baseline, identify the highest-impact bottleneck with evidence, implement focused improvements, compare before and after under equivalent conditions, and add regression protection. Do not use for general feature work, visual redesign, standalone security review, cloud architecture, or cost optimization without a measured performance problem."
Ship It: Performance
Improve one important product journey with measurements users can feel and reviewers can reproduce. Optimize the bottleneck, not the most fashionable layer or an isolated benchmark score.
Commit to a measurable outcome
- Treat the product blueprint, critical frontend flow, backend contract, security handoff, repository, and available telemetry as inputs.
- Respect the requested mode. For diagnosis, measure and report without editing. For optimization, implement focused changes and verify them.
- Preserve correctness, security invariants, accessibility, data freshness, and product behavior. Never gain speed by weakening authorization, validation, privacy, durability, or user feedback.
- Ask only when the target journey, representative workload, environment, production testing authority, or a behavior-changing tradeoff cannot be inferred safely.
- Do not run load tests against production or third-party services without explicit authorization. Prefer local, test, or staging environments with bounded traffic.
- Preserve the existing stack and observability patterns. Add dependencies only when existing tools cannot produce the evidence needed.
- Do not promise scale, capacity, or production latency from a development-machine benchmark alone.
Inspect the system and its constraints
- Read repository instructions, manifests, build configuration, deployment assumptions, test commands, telemetry, and the current worktree.
- Trace the critical journey across browser work, network requests, server handlers, external calls, database access, serialization, queues, and rendering.
- Inspect nearby performance patterns: pagination, indexes, caches, batching, streaming, image and font handling, code splitting, connection pools, timeouts, and limits.
- Identify the security constraints from the previous stage, especially tenant isolation, authorization, rate limits, sensitive data, and cache boundaries.
- Choose an environment and dataset representative enough for the decision. Record important differences from production.
Prefer an end-to-end trace of the slow journey before profiling individual functions.
Define the performance contract
Write a compact contract before changing code:
- Journey: the user action or system operation being improved.
- Workload: data size, concurrency, request mix, device, network, cache state, and warm or cold conditions.
- Primary metric: the one measure that best represents user or operational impact.
- Guardrails: correctness, errors, freshness, memory, CPU, database load, bundle size, or cost signals that must not regress.
- Target: an existing product budget, or a clearly labeled proposed target when none exists.
- Environment: exact command, build mode, runtime, dataset, and tooling needed to reproduce the measurement.
Choose only relevant metrics:
| Surface | Useful measures |
|---|---|
| User experience | LCP, INP, CLS, time to usable content, interaction completion time |
| Network and frontend | TTFB, request count, transferred bytes, critical resource timing, JavaScript and CSS size, render count |
| API and jobs | p50/p95/p99 latency, throughput, error rate, queue delay, work per operation |
| Database | query count, query time, rows scanned, plan shape, lock time, connection use |
| Runtime | CPU time, memory, allocations, event-loop or thread saturation, garbage collection |
Do not substitute a synthetic score for the product metric it approximates.
Establish a trustworthy baseline
- Build and run in the mode relevant to release; do not compare a development build with a production build.
- Warm up runtimes when appropriate, then run enough repetitions to expose variance. Report a distribution or median and tail, not only the best run.
- Keep hardware, dataset, cache state, concurrency, network conditions, and measurement tooling equivalent between comparisons.
- Capture correctness and error rate with the timing. A faster failed request is not an improvement.
- Save the command and key settings needed to reproduce the baseline. Use existing benchmark or profiling harnesses when available.
- Mark noisy, simulated, or environment-limited measurements honestly.
If no credible baseline can be obtained, stop short of claiming an improvement. Report the instrumentation or environment gap instead.
Locate the dominant bottleneck
Decompose elapsed time or resource use across the journey, then use the closest evidence source:
- browser performance traces, network waterfalls, component profilers, and bundle analyzers;
- server traces, request timing, sampling or instrumenting profilers, and structured logs;
- database query logs, query plans, row estimates, lock observations, and query counts;
- queue timing, dependency timing, allocation profiles, and saturation metrics.
Form one testable hypothesis at a time. Prefer the bottleneck with the highest user impact, evidence confidence, and reversible improvement cost. Reject changes whose theoretical benefit is outside the measured hot path.
Optimize the responsible layer
Apply the smallest change that remove
Read the complete source ↗