# Performance Review

> Review frontend code changes for performance anti-patterns and guideline compliance. Checks query hooks, stale times, bundle impact, rendering patterns, and Zustand selectors. Use when this capability is needed.

- Skill: `tomevault-io/performance-review` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/performance-review`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/performance-review/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/performance-review

---


# Frontend Performance Review

**Reference:** `frontend/docs/performance.md`

---

## When to Invoke

- Before submitting a PR that adds or modifies query hooks, page components, Zustand stores, or real-time features
- When the user asks for a "performance review" or "perf check"
- As part of the component-development workflow for new pages

## Agent Instructions

When invoked, perform the following checks in order. Report PASS/FAIL/WARN for each. Group failures by severity: **CRITICAL** (must fix before merge), **WARNING** (should fix), **INFO** (consider).

### Step 1: Identify Scope

Read the diff or the files specified by the user. If no files specified, use `git diff --name-only` to find changed frontend files. Identify which categories apply: query hooks, page routes, stores, real-time, bundle.

### Step 2: Query Hook Checks

1. Search for `useState` + `useEffect` + `api.` within 20 lines of each other in changed files. If found: **CRITICAL** — should be a TanStack Query hook.
2. Check that new `useQuery` calls reference a key from `queryKeys.ts`, not an inline array. If inline: **CRITICAL**.
3. Check that new query hook files are named `use<Domain>Queries.ts` and placed in `src/hooks/queries/`. If misplaced: **WARNING**.
4. Check that `useMutation` calls include `onSuccess` with `queryClient.invalidateQueries()`. If missing: **WARNING**.
5. Check for `skipToken` usage on conditional queries vs. `enabled: false`. Flag `enabled: false` without `skipToken` as **WARNING**.

### Step 3: Stale Time Audit

1. For each new `useQuery`, check if `staleTime` is set explicitly or inherits the 30s default appropriately.
2. Cross-reference the data type: if the query fetches components, templates, or providers — flag missing `staleTime: Infinity` as **CRITICAL**.
3. For execution queries, verify they use `executionQueryOptions.ts` factories rather than inline values. Flag inconsistency as **WARNING**.
4. For queries on terminal runs, verify `terminalStaleTime()` is used rather than a hardcoded number.

### Step 4: Bundle Impact

1. For each new page added to `App.tsx`: verify it uses `React.lazy(() => import(...))`. Static imports are **CRITICAL**.
2. Verify new sidebar pages are added to `routePrefetchMap` in `src/lib/prefetch-routes.ts`. Missing entry is **WARNING**.
3. If a new conditionally-visible component imports a library > 100KB (check for `@xterm`, `posthog-js`, `lucide-react` barrel imports): flag as **WARNING** — consider deferred load pattern.

### Step 5: Rendering Checks

1. Search for `const [*, set*] = useState` followed by `set*` inside a `useEffect` that references query data — **CRITICAL** (should use `useMemo`).
2. Look for derived data calculations inline in JSX without `useMemo` involving array operations (filter, sort, reduce) — **WARNING**.
3. Check for `React.memo` usage on new components in `timeline/` or `workflow/` directories that re-render frequently — **INFO** if missing.

### Step 6: Zustand Store Checks

1. Search for `const store = use<X>Store()` or destructuring from `use<X>Store()` without a selector — full store subscription. **WARNING**.
2. For new stores using `persist`, verify `partialize` is present. Missing is **WARNING**.
3. For new `persist` stores, verify action functions are excluded from `partialize`.

### Step 7: Generate Report

Format the output as follows:

```
## Performance Review: [description of scope]

### Critical (must fix before merge)
- [file:line] Description of issue. See: performance.md § [section]

### Warnings (should fix)
- [file:line] Description of issue. See: performance.md § [section]

### Info (consider)
- [file:line] Description. See: performance.md § [section]

### Passed Checks
- [n] query hooks using TanStack Query correctly
- [n] page routes using React.lazy
- [n] Zustand selectors properly scoped
- staleTime: appropriate tiers applied

### Summary
[1-2 sentences on overall performance hygiene of the change]
```

## Rules

- This is a **review only** — do NOT make code changes unless the user explicitly asks
- Always cite the file and line number for each finding
- Always reference `frontend/docs/performance.md` for the relevant pattern section
- If no frontend files are in the diff, report "No frontend changes detected" and exit

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/shipsecai) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->