NodeJSmith/i-optimize

Identify and fix performance issues to create faster, smoother user experiences.

MANDATORY PREPARATION

Read ${CLAUDE_CONFIG_DIR:-~/.claude}/skills/i-frontend-design/SKILL.md for design principles, anti-patterns, and the Context Gathering Protocol. Follow the protocol before proceeding — if no design context exists yet, you MUST run /i-teach-impeccable first.

---

Assess Performance Issues

Understand current performance and identify problems:

1. Measure current state:

   • Core Web Vitals: LCP, FID/INP, CLS scores
   • Load time: Time to interactive, first contentful paint
   • Bundle size: JavaScript, CSS, image sizes
   • Runtime performance: Frame rate, memory usage, CPU usage
   • Network: Request count, payload sizes, waterfall

2. Identify bottlenecks:

   • What's slow? (Initial load? Interactions? Animations?)
   • What's causing it? (Large images? Expensive JavaScript? Layout thrashing?)
   • How bad is it? (Perceivable? Annoying? Blocking?)
   • Who's affected? (All users? Mobile only? Slow connections?)

CRITICAL: Measure before and after. Premature optimization wastes time. Optimize what actually matters.

---

Propose Changes

After analyzing the current state, present your proposed changes to the user:

1. Assessment: What's wrong and why (your domain analysis above)
2. Proposed changes: Specific changes ranked by impact, with rationale
3. Verification plan: What to check after implementation (LLM self-check items + Playwright verification if available)

Then STOP and confirm before implementing:

AskUserQuestion:
  question: "Here's what I propose. How would you like to proceed?"
  header: "Confirm"
  options:
    - label: "Implement"
      description: "Looks good — go ahead and make these changes."
    - label: "Refine scope"
      description: "I want to adjust what's included before you start."
    - label: "Challenge this first"
      description: "I'll run /mine-challenge against your proposal before we proceed."
    - label: "Stop here"
      description: "Don't implement anything. The proposal is in this conversation only."

If "Implement" → proceed to implementation below. If "Refine scope" → ask what to change, update proposal, re-confirm.

<!-- CHALLENGE-CALLER -->

If "Challenge this first" → invoke /mine-challenge inline against the proposal, read findings, revise proposal, re-present this gate. If "Stop here" → end the skill.

---

Optimization Strategy

The standard techniques are familiar — apply the ones the trace points to:

• Loading: modern image formats + srcset/loading="lazy" at display size; route/component code splitting and dynamic imports; critical CSS inline; font-display: swap with subsetting and preload.
• Rendering: batch DOM reads then writes (never alternate — that forces reflow per iteration); content-visibility: auto and virtual scrolling for long lists; CSS contain for independent regions.
• Animation: animate only transform/opacity (GPU-composited), never layout properties; requestAnimationFrame for JS animation; will-change sparingly.
• React: memo/useMemo/useCallback on measured-expensive work only; virtualize long lists; no inline function creation in hot render paths; profile before sprinkling memos.
• Network: paginate, compress (brotli/gzip), cache headers, CDN; drop unused third-party scripts; adaptive loading on slow connections.

Core Web Vitals Optimization

Largest Contentful Paint (LCP < 2.5s)

• Optimize hero images
• Inline critical CSS
• Preload key resources
• Use CDN
• Server-side rendering

First Input Delay (FID < 100ms) / INP (< 200ms)

• Break up long tasks
• Defer non-critical JavaScript
• Use web workers for heavy computation
• Reduce JavaScript execution time

Cumulative Layout Shift (CLS < 0.1)

• Set dimensions on images and videos
• Don't inject content above existing content
• Use aspect-ratio CSS property
• Reserve space for ads/embeds
• Avoid animations that cause layout shifts

/* Reserve space for image */
.image-container {
  aspect-ratio: 16 / 9;
}

Performance Monitoring

Tools to use:

• Chrome DevTools (Lighthouse, Performance panel)
• WebPageTest
• Core Web Vitals (Chrome UX Report)
• Bundle analyzers (webpack-bundle-analyzer)
• Performance monitoring (Sentry, DataDog, New Relic)

Key metrics:

• LCP, FID/INP, CLS (Core Web Vitals)
• Time to Interactive (TTI)
• First Contentful Paint (FCP)
• Total Blocking Time (TBT)
• Bundle size
• Request count

IMPORTANT: Measure on real devices with real network conditions. Desktop Chrome with fast connection isn't representative.

NEVER:

• Optimize without measuring (premature optimization)
• Sacrifice accessibility for performance
• Break functionality while optimizing
• Use will-change everywhere (creates new layers, uses memory)
• Lazy load above-fold content
• Optimize micro-optimizations while ignoring major issues (optimize the biggest bottleneck first)
• Forget about mobile performance (often slower devices, slower connections)

Verify Improvements

Test that optimizations worked:

• Before/after metrics: Compare Lighthouse scores
• Real user monitoring: Track improvements for real users
• Different devices: Test on low-end Android, not just flagship iPhone
• Slow connections: Throttle to 3G, test experience
• No regressions: Ensure functionality still works
• User perception: Does it feel faster?

Remember: Performance is a feature. Fast experiences feel more responsive, more polished, more professional. Optimize systematically, measure ruthlessly, and prioritize user-perceived performance.

Completion

After implementation, summarize in conversation:

1. Changes made: List each file changed and what was done
2. Verification: LLM self-check results (anti-pattern scan, consistency check). Note if Playwright was available for visual verification.
3. Suggested next step: Any follow-up skills that would complement this work (e.g., after /i-typeset, suggest /i-polish for a final pass)