playbooks

home / skills / velcrafting / codex-skills / performance-pass-ui

performance-pass-ui skill

/skills/frontend/performance-pass-ui

This skill helps identify and reduce UI performance regressions by applying targeted optimizations with minimal, verifiable code changes.

npx playbooks add skill velcrafting/codex-skills --skill performance-pass-ui

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
3.0 KB
---
name: performance-pass-ui
description: Identify and reduce avoidable UI performance regressions (render churn, heavy computations, oversized bundles) without behavior change.
metadata:
  short-description: UI perf pass
  layer: frontend
  mode: write
  idempotent: true
---

# Skill: frontend/performance-pass-ui

## Purpose
Improve UI performance by removing obvious regressions and hotspots:
- unnecessary rerenders
- expensive derived computations on render
- unbounded lists or heavy DOM
- avoidable bundle bloat and lazy-load misses

This is a focused pass. It should not change user-facing behavior.

---

## Inputs
- Target UI surface (route/component)
- Reported symptom (slow render, jank, laggy typing, long TTI) if known
- Repo profile (preferred): `<repo>/REPO_PROFILE.json` (framework/tooling/commands)
- Existing instrumentation (React DevTools Profiler, performance marks, logs) if present

---

## Outputs
- Minimal code changes improving performance
- Notes in code comments where tradeoffs exist (why memoization, why virtualization, etc.)
- Optional: small measurement note in PR summary (before/after) if measurement is available

---

## Non-goals
- Visual redesign
- Refactoring purely for style
- Introducing new dependencies unless repo standard
- Premature micro-optimizations without evidence

---

## Workflow
1) Establish baseline:
   - reproduce issue or identify likely hot path
   - prefer measurable evidence (profiler, devtools, timing marks)
2) Identify top offenders:
   - rerender cascades (props identity churn)
   - heavy computations in render
   - large lists without virtualization
   - excessive re-fetch or revalidation loops
3) Apply smallest effective fix:
   - memoize derived values (`useMemo`) only when computation is non-trivial
   - stabilize callbacks (`useCallback`) only when it prevents churn
   - split components to reduce rerender surface
   - add list virtualization if large lists
   - add lazy loading for heavy routes/components if repo uses it
4) Verify behavior unchanged:
   - same UI output and interaction
5) Run validations from profile.

---

## Checks
- No user-visible behavior change (same UI states and interactions)
- Typecheck/lint pass if configured
- Performance improvement is plausible and localized:
  - fewer renders in hot path OR
  - reduced work per render OR
  - reduced payload/deferral of heavy components
- No new infinite loops (effects, memo deps, query invalidations)

---

## Failure modes
- No evidence of perf issue → add minimal measurement first or decline changes.
- Memoization causes stale UI → fix dependencies or remove optimization.
- Optimization increases complexity too much → revert and propose a safer alternative.
- Large list performance issues → recommend virtualization; if not allowed, limit rendered rows.

---

## Telemetry
Log:
- skill: `frontend/performance-pass-ui`
- target: `<route/component>`
- techniques: `memo | split | virtualization | lazy-load | effect-fix | other`
- files_touched
- outcome: `success | partial | blocked`

Overview

This skill identifies and reduces avoidable UI performance regressions without changing user-visible behavior. It focuses on render churn, expensive computations during render, oversized bundles, and unbounded DOM work. Changes are minimal and evidence-driven, with notes in code for any tradeoffs.

How this skill works

Provide a target route or component and any reported symptom or existing profiler output. I reproduce or measure the hotspot, identify top offenders (props identity churn, heavy computations, large lists, lazy-load misses), and apply the smallest effective fixes such as memoization, component splitting, virtualization, or lazy loading. I verify no behavioral change, run project validations, and record telemetry about techniques and outcome.

When to use it

  • Slow initial render, long time-to-interactive, or janky animations
  • Noticeable lag while typing or interacting with a specific view
  • Large lists rendering all items without virtualization
  • Profiler shows frequent or expensive re-renders in a component tree
  • Bundle size growth causing expensive route loads or long parse time

Best practices

  • Start with measurable evidence (profiler/timing) before optimizing
  • Make the smallest targeted change that preserves UI behavior
  • Memoize derived values only when computation is non-trivial and dependencies are correct
  • Stabilize callbacks selectively to eliminate prop identity churn
  • Prefer splitting or lazy-loading heavy routes/components over adding new dependencies

Example use cases

  • Reduce re-render cascade in a dashboard by splitting a metrics widget and memoizing derived props
  • Fix laggy input by removing expensive synchronous computations from the render path
  • Add virtualization to a long table to cut DOM nodes and reduce frame time
  • Lazy-load a large charting component to improve route TTI without changing visuals
  • Replace repeated effect-triggered fetches with guarded effects to stop revalidation loops

FAQ

Will this change the UI or user experience?

No. The intent is to preserve identical UI states and interactions while reducing unnecessary work under the hood.

Do you add new dependencies to the project?

Only if the repository standard already uses them; otherwise I prefer built-in techniques like memoization, splitting, or native lazy loading.

What if there is no profiling data?

I add minimal measurement first to establish a baseline and avoid blind micro-optimizations; if profiling is impossible, I point out safe, low-risk improvements or decline.