Skip to content

EliasOulkadi/shokunin / .pack/skills/performance-profiler

performance-profiler

Flagged

Performance profiling and optimization for web apps — Core Web Vitals (LCP, INP, CLS), Lighthouse audits, bundle analysis, backend profiling (CPU, memory, DB queries), N+1 detection, caching strategies (Redis, CDN, HTTP), and performance budgets. Use when user asks to improve performance, run Lighthouse audit, profile a Node.js app, optimize Core Web Vitals, reduce bundle size, or investigate slow response times. Do NOT use for database schema optimization (use db-sculptor), Docker image optimization (use docker), or CDN configuration.

Performance Profiler

Find and fix performance issues from frontend to backend. Based on Google Core Web Vitals, Lighthouse, Chrome DevTools, and production patterns from WebPageTest and clinic.js.

Sub-Commands

CommandDescription
auditRun comprehensive performance audit (frontend + backend)
vitalsAudit Core Web Vitals specifically (LCP, INP, CLS, TBT)
lcpOptimize Largest Contentful Paint
inpFix Interaction to Next Paint (long tasks)
bundleAnalyze bundle size and split strategy
backendProfile Node.js/Python backend performance
budgetSet and verify performance budgets

Workflow

Step 1: Run Lighthouse audit (exact command)

npx lighthouse https://example.com --preset=desktop --output=html --output-path=./lighthouse-report.html
npx lighthouse https://example.com --preset=desktop --output=json --output-path=./lighthouse.json

Target scores:

MetricTargetSeverity if missed
Performance> 90Critical
LCP (Largest Contentful Paint)< 2.5sCritical
INP (Interaction to Next Paint)< 200msCritical
CLS (Cumulative Layout Shift)< 0.1Critical
TBT (Total Blocking Time)< 200msHigh
FCP (First Contentful Paint)< 1.8sMedium
Speed Index< 3.4sMedium

Step 2: Fix Core Web Vitals

LCP optimization (exact fixes)

<!-- 1. Preload LCP image -->
<link rel="preload" as="image" href="hero.webp" fetchpriority="high">

<!-- 2. LCP image: no lazy loading -->
<img src="hero.webp" width="1200" height="600" fetchpriority="high" alt="">

<!-- 3. Inline critical CSS in <head> -->
<style>
  .hero { display: grid; min-height: 100dvh; }
  .hero img { width: 100%; height: auto; aspect-ratio: 2/1; }
</style>

<!-- 4. Defer non-critical CSS -->
<link rel="preload" href="styles.css" as="style" onload="this.onload=null;this.rel='stylesheet'">

<!-- 5. Self-host fonts with font-display: swap -->
@font-face {
  font-family: 'Geist';
  src: url('/fonts/geist.woff2') format('woff2');
  font-display: swap;
}

LCP sub-parts breakdown:

  1. TTFB (Time to First Byte): < 800ms. Optimize server response. CDN. Caching.
  2. Resource load delay: Preload + fetchpriority + no render-blocking.
  3. Resource load time: Compress, CDN, modern format (WebP/AVIF).
  4. Element render delay: Inline critical CSS. No layout-shifting JS above fold.

INP optimization (long task breakup)

// Break up long tasks with scheduler.yield()
async function processLargeDataset(items: Item[]) {
  const CHUNK_SIZE = 50

  for (let i = 0; i < items.length; i += CHUNK_SIZE) {
    const chunk = items.slice(i, i + CHUNK_SIZE)
    processChunk(chunk)

    if (i + CHUNK_SIZE < items.length) {
      // Yield to main thread every 50ms
      await new Promise(resolve => setTimeout(resolve, 0))
    }
  }
}

// Or use scheduler.yield() (Chrome 115+)
for (let i = 0; i < items.length; i += CHUNK_SIZE) {
  processChunk(items.slice(i, i + CHUNK_SIZE))
  await scheduler.yield()
}

Common INP causes:

  • Expensive event handlers (click, keydown, input)
  • Synchronous layout reads/writes (layout thrashing)
  • Large DOM manipulations in single frame
  • JSON.parse() on large payloads (> 50KB)

CLS optimization

/* Reserve space for images */
img, video, iframe {
  width: 100%;
  height: auto;
  aspect-ratio: attr(width) / attr(height);
}

/* Reserve space for dynamic content */
.ad-container {
  min-height: 250px;
}

/* Prevent layout shift from web fonts */
body {
  font-display: swap;
}

/* Fixed size for injected elements */
.cookie-banner {
  min-height: 80px;
}

Step 3: Profile backend

# Node.js CPU profile
node --cpu-prof --cpu-prof-interval=1 server.js
# Analyze: clinic doctor -- node server.js

# Node.js heap snapshot
node --heapsnapshot server.js
# Load in Chrome DevTools > Memory tab

# Python profiling
python -m cProfile -o output.prof server.py
# Analyze: snakeviz output.prof
SymptomLikely causeFix
High CPUN+1 queries, synchronous cryptoAdd eager loading. Use async operations.
High memoryNo streaming. Array growth.Stream responses. Paginate results.
High latency p99DB lock contentionAdd indexes. Use read replicas.
GC pausesHigh allocation ratePool objects. Reduce allocations. Use Buffer pools.
Connection timeoutsPool exhaustionIncrease pool size. Add connection queue.

Step 4: Bundle analysis

# Next.js
ANALYZE=true next build

# Vite/Rollup
npx vite-bundle-visualizer

# Generic
npx source-map-explorer dist/**/*.js
TargetBudget
Total JS< 300KB (gzipped)
Total CSS< 50KB (gzipped)
Total fonts< 100KB
First load JS< 100KB (gzipped)
Total image payload< 500KB
Largest chunk< 150KB (gzipped)

Step 5: Caching strategy decision tree

WhatCache whereTTL
Static assets (JS, CSS, images)CDN + browser1 year (versioned filenames)
API responses (public, stable)CDN + HTTP Cache-Control5 min to 1h (stale-while-revalidate)
Dynamic data (user-specific)Redis30s to 5min
Database query resultsApplication memory (LRU)10s
Full pages (public)CDN + Edge caching5 min
Auth tokensNever cache—

Step 6: Performance budgets in CI

{
  "ci": {
    "assert": {
      "assertions": {
        "categories:performance": ["error", { "minScore": 0.9 }],
        "largest-contentful-paint": ["error", { "maxNumericValue": 2500 }],
        "interactive": ["error", { "maxNumericValue": 3800 }],
        "total-blocking-time": ["error", { "maxNumericValue": 200 }],
        "cumulative-layout-shift": ["error", { "maxNumericValue": 0.1 }],
        "resource-summary:script:size": ["warn", { "maxNumericValue": 300000 }]
      }
    }
  }
}
npx lighthouse https://staging.example.com --output=json | \
  npx lighthouse-ci --collect --assert

Production Checklist

  • Lighthouse Performance > 90 (mobile throttled)
  • LCP < 2.5s (p75 field data)
  • INP < 200ms (p75 field data)
  • CLS < 0.1 (p75 field data)
  • Bundle: JS < 300KB, CSS < 50KB (gzipped)
  • Images: WebP/AVIF, srcset, lazy loading below fold
  • Fonts: self-hosted, font-display: swap, subset
  • Critical CSS inlined, rest deferred
  • Hero image preloaded with fetchpriority="high"
  • Server response < 200ms (p95)
  • N+1 queries detected and fixed
  • CDN + HTTP caching configured
  • CI: Lighthouse budget enforcement
  • RUM (Real User Monitoring) configured

Anti-Patterns

Anti-patternFix
Optimizing without measuringAlways measure first. Field data > lab data.
Only testing on dev machineTest on real devices with throttling (3G, 4x CPU slowdown)
Cache everythingCache only what changes infrequently. Stale cache is worse than no cache.
Lazy loading above-fold imagesOnly lazy load below-fold. LCP image must load immediately.
Bundle splitting too aggressivelySplit at route boundaries. Not by component.
Optimizing non-bottleneckUse Lighthouse + RUM to find actual bottleneck.
Ignoring mobileMobile is 2-4x slower than desktop. Optimize for mobile first.
No performance budgetCI must fail when budget exceeded.

Sources

  • web.dev — Core Web Vitals
  • Lighthouse documentation
  • Addy Osmani — Performance optimization patterns
  • Paul Lewis — RequestAnimationFrame, compositor-only properties
  • Node.js performance guide
  • clinic.js — Node.js profiling
  • WebPageTest — Real device testing
  • Chrome UX Report — Field data for Core Web Vitals

Error Handling

CauseFix
Lighthouse audit crashes on SPA with hash routingUse --chrome-flags="--disable-web-security" or serve localhost via static server, never file://
Lighthouse scores vary 5+ points between runsNormal. Run 3-5 times, use median. Always audit Incognito with no extensions. Variance from network jitter and CPU scheduling
Bundle analyzer can't parse source maps — blank treemapVerify devtool: 'hidden-source-map' in webpack/Vite. Regenerate build with source maps enabled. Check sourceMapFilename matches
RUM field data shows much worse LCP than lab (Lighthouse)Lab is synthetic (fast CPU/network). Field data from real users on slow devices. Trust field data. Optimize for p75, not median
Performance budget assertion fails CI on every PRInvestigate which chunk exceeded budget immediately. Treat as build failure. Block merge until resolved or budget explicitly raised with justification
Chrome DevTools Performance tab freezes on large trace (>30s)Record shorter traces (5-10s max). Use --user-data-dir with clean profile. Export HAR for sharing instead of full trace
clinic doctor fails with "Cannot find module"Works only with Node.js < 22. For Node 22+, use node --cpu-prof and analyze with Chrome DevTools. clinic is community-maintained, lagging Node releases
WebPageTest results vary significantly by test locationTest from 2+ geographic regions. Use medianRun and repeatView in WPT API. Document which locations were tested in audit report

Checklist

  • Skill loads without errors in the AI agent
  • YAML frontmatter is valid (description, compatibility, audience)
  • Workflow section provides clear step-by-step instructions
  • Error handling section covers common failure modes
  • All referenced files (references/, scripts/, assets/) exist
  • Skill triggers correctly for intended use cases
  • No broken links or missing resources
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall