--- name: performance-optimization-ae7c6e92a55f description: | Measure-first optimization for code that has actual evidence of being slow. Apply when performance requirements exist, profiles show bottlenecks, or a change introduced a regression. Triggers on "optimize", "performance", "slow", "profile", "bottleneck", "core web vitals", "regression". allowed-tools: Read, Edit, Bash, Grep, Glob --- # Performance Optimization Skill ## When to apply - Performance requirements are stated in the spec or issue (e.g., "list endpoint must p95 < 200ms") - Users or monitoring report slow behavior with a reproducible scenario - Core Web Vitals scores fall below "Good" thresholds (LCP < 2.5s, INP < 200ms, CLS < 0.1) - A specific commit or PR introduced a measurable regression vs prior baseline - Code handles datasets large enough that complexity dominates (n > 10k or rps > 100) **Skip when:** - There's no measurement showing a problem — "feels slow" without a profile is not a justification - The fix would add complexity disproportionate to the win (5% improvement at the cost of unreadable code) - Performance is dominated by a downstream system you don't control (e.g., the LLM round-trip) - The hot path is run once per cold-start — micro-optimizing startup isn't worth the readability cost > "Premature optimization is the root of all evil." Don't optimize before you have evidence. The cost of complexity is permanent; the cost of waiting for evidence is one more profile run. ## The MIFVG cycle 1. **MEASURE** — establish baseline with real data. Synthetic benchmarks are starting points, not ground truth. Capture both p50 and p95. 2. **IDENTIFY** — profile. Don't guess the bottleneck — measure it. Tools: `node --prof`, `clinic.js`, browser DevTools Performance, `pprof` for memory. 3. **FIX** — address the specific bottleneck. One change at a time. If two things are slow, fix the worst one first and re-measure. 4. **VERIFY** — re-measure with the same scenario. The improvement must be reproducible, not a single lucky run. 5. **GUARD** — add a monitoring assertion, a test budget, or a performance gate so the fix doesn't silently regress. The Beyoncé Rule applies — if you measured it, put a guard on it. ## Common patterns to fix (when evidence supports) | Pattern | Symptom | Fix | | ---------------------------------------- | ----------------------------------------------------- | --------------------------------------------------------------------- | | **N+1 queries** | One query per record in a loop | Single batched query with `IN` clause or proper join | | **Unbounded data** | Fetching all rows when 50 would do | Pagination + cursor-based limits | | **Synchronous I/O in hot path** | `readFileSync`, `execSync` per request | Async + worker pool, or cache the result | | **Unnecessary serialization** | JSON-parse-and-stringify the same blob multiple times | Pass through, or hash-cache by input | | **Cache miss patterns** | Read-only data fetched on every render/request | TTL cache or memoization (with size bound) | | **Bundle size growth** | First-paint regression after a feature add | Dynamic import for heavy features, code splitting at route boundaries | | **Re-render storms (React/Svelte/etc.)** | Component renders 100x for one state change | Stable references, key-based memoization, lift state up | ## Anti-rationalization — Performance | Excuse | Counter | | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | "I'll add the optimization while I'm in here" | Optimization without a profile is gambling. The added complexity is permanent; the win may be zero or negative. | | "Big-O says it's faster" | Big-O is asymptotic. For your actual `n`, the constant factors and cache effects often dominate. Measure. | | "JavaScript engines optimize this" | Modern engines optimize hot loops, not your data flow. Don't assume — profile. | | "It's a tiny win but free" | Free in code, expensive in review and bisect. Many "tiny wins" together obscure the actual hot path. | | "Premature optimization is fine if it's clean" | The dichotomy isn't "messy vs clean optimization." It's "with evidence vs without." Without evidence, even clean optimization is premature. | | "We'll measure in production" | You won't. Production has too much noise. Build a representative reproduction first. | ## Red flags - Optimization PR with no before/after numbers - "Optimization" that's actually a refactor disguised as a perf win - Removing logging, validation, or error handling "for performance" without a profile justifying it - Use of `useMemo` / `React.memo` / `signal()` everywhere as a precaution - Bundle size grew significantly with no entry in the changelog - New caching layer without a documented invalidation strategy or size bound ## Verification checklist - [ ] Before/after measurements with specific numbers (p50 and p95) attached to the PR - [ ] Reproduction scenario documented so the next reviewer can verify - [ ] The bottleneck was identified by profiler, not guessed - [ ] Existing tests still pass: `pnpm lint && pnpm typecheck && pnpm test` - [ ] Bundle size hasn't increased (run a size check if the PR touches the website or CLI bundle) - [ ] No new caching without an invalidation/size strategy - [ ] Performance guard added (test budget, monitoring threshold, or CI gate) to prevent silent regression - [ ] If applicable: Core Web Vitals still in "Good" thresholds after the change --- Source attribution: nexus-substrate Original project: https://github.com/nexus-substrate/nexus-agents/blob/ddc209542969af8515e8424e45f93905e445d81c/skills/performance-optimization/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Mega AI Hub. ## Upstream license notice MIT License Copyright (c) 2026 William Zujkowski Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ## Additional upstream notices performance-optimization-ae7c6e92a55f/DAVEAI-UPSTREAM-NOTICE nexus-agents Copyright (c) 2026 William Zujkowski This project is inspired by and incorporates concepts from claude-team-mcp, which is also licensed under the MIT License. Attribution is preserved per the terms of the original license. # Mega AI Hub resource metadata Creator / publisher: nexus-substrate Original project: https://github.com/nexus-substrate/nexus-agents/blob/ddc209542969af8515e8424e45f93905e445d81c/skills/performance-optimization/SKILL.md Attribution basis: Source repository record Fields of work: Development & Engineering, Product Management Roles: Backend Developer, Frontend Developer, Full-Stack Developer, Product Manager, QA / Test Engineer Specialties: Backend, Cross Platform, Frontend Tools: Bash Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: 0068f357b24c2e9d5ccd6562e393c67f287f05e5994d0db952160699801497ad