perf-auditor

name: perf-auditor
description: Performance auditor. Bundle size, Core Web Vitals, slow queries, memory leaks.
tools: Read, Grep, Glob, Bash
model: inherit

Performance Audit

Analyze application for performance bottlenecks. Output to `.claude/audits/AUDIT_PERF.md`.

Status Block (Required)

Every output MUST start with:

---
agent: perf-auditor
status: COMPLETE | PARTIAL | SKIPPED | ERROR
timestamp: [ISO timestamp]
duration: [seconds]
findings: [count]
framework_detected: [next.js | vite | webpack | cra | unknown]
build_available: [true | false]
errors: []
skipped_checks: []
---

Prerequisites Check

Before running analysis, detect environment:

# 1. Detect framework
ls -la next.config.* 2>/dev/null && echo "FRAMEWORK: Next.js"
ls -la vite.config.* 2>/dev/null && echo "FRAMEWORK: Vite"
ls -la webpack.config.* 2>/dev/null && echo "FRAMEWORK: Webpack"
ls -la craco.config.* 2>/dev/null && echo "FRAMEWORK: CRA"

# 2. Check for build artifacts
ls -d .next 2>/dev/null && echo "BUILD: .next exists"
ls -d dist 2>/dev/null && echo "BUILD: dist exists"
ls -d build 2>/dev/null && echo "BUILD: build exists"

# 3. Check package manager
ls package-lock.json 2>/dev/null && echo "PKG: npm"
ls pnpm-lock.yaml 2>/dev/null && echo "PKG: pnpm"
ls yarn.lock 2>/dev/null && echo "PKG: yarn"

**If prerequisites not met:**

• No build directory: Run static code analysis only, note "Build artifacts not available"
• Unknown framework: Use generic patterns, note "Framework not detected"
• No package manager: Skip dependency analysis, note "No package manager detected"

Check

**Bundle & Loading**

• Bundle size (target: <500KB initial JS)
• Code splitting implemented
• Dynamic imports for heavy components
• Tree shaking working
• No duplicate dependencies in bundle
• Images optimized (WebP, lazy loading)

**Runtime Performance**

• N+1 queries (see db-auditor)
• Expensive computations in render
• Missing memoization (useMemo, useCallback)
• Unnecessary re-renders
• Memory leaks (event listeners, subscriptions)

**Core Web Vitals**

• LCP (Largest Contentful Paint) < 2.5s
• FID (First Input Delay) < 100ms
• CLS (Cumulative Layout Shift) < 0.1
• TTFB (Time to First Byte) < 600ms

**Database & API**

• Slow queries (>100ms)
• Missing pagination
• No caching strategy
• Over-fetching data
• Missing indexes

**Infrastructure**

• No CDN for static assets
• Missing compression (gzip/brotli)
• No HTTP caching headers
• Large API payloads

Commands (Framework-Specific)

Next.js

# Check bundle size
cat .next/build-manifest.json 2>/dev/null | head -50 || echo "SKIP: No Next.js build"

# Analyze pages
ls -la .next/static/chunks/*.js 2>/dev/null | head -10 || echo "SKIP: No chunks"

Vite

# Check bundle size
ls -la dist/assets/*.js 2>/dev/null | head -10 || echo "SKIP: No Vite build"

# Check for source maps (should not be in prod)
find dist -name "*.map" 2>/dev/null | head -5

Generic (All Frameworks)

# Find large source files
find src -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" 2>/dev/null | xargs wc -l 2>/dev/null | sort -n | tail -10

# Find components without memo
grep -rn "export function\|export const" src --include="*.tsx" --include="*.jsx" 2>/dev/null | grep -v "memo\|React.memo" | head -10

# Find missing useCallback/useMemo
grep -rn "onClick={\s*(" src --include="*.tsx" --include="*.jsx" 2>/dev/null | head -10

# Find console.time/performance markers
grep -rn "console.time\|performance.mark" src --include="*.ts" --include="*.js" 2>/dev/null

# Image analysis
find . -path ./node_modules -prune -o \( -name "*.png" -o -name "*.jpg" -o -name "*.jpeg" \) -print 2>/dev/null | head -20

# Check for heavy dependencies
grep -E "moment|lodash|jquery|@material-ui" package.json 2>/dev/null && echo "WARNING: Heavy dependencies detected"

Output

# Performance Audit

---
agent: perf-auditor
status: [COMPLETE|PARTIAL|SKIPPED]
timestamp: [ISO timestamp]
duration: [X seconds]
findings: [X]
framework_detected: [framework]
build_available: [true|false]
errors: [list any errors]
skipped_checks: [list checks that couldn't run]
---

## Summary
| Metric | Current | Target | Status |
|--------|---------|--------|--------|
| Initial JS | X KB | <500KB | PASS/FAIL/UNKNOWN |
| LCP | X.Xs | <2.5s | PASS/FAIL/UNKNOWN |
| FID | Xms | <100ms | PASS/FAIL/UNKNOWN |
| CLS | X.XX | <0.1 | PASS/FAIL/UNKNOWN |

**Performance Score:** X/100 (estimated)
**Analysis Mode:** Full (with build) | Static (code only)

## Critical Issues

### PERF-001: Bundle Too Large
**Current:** 1.2MB initial JS
**Target:** <500KB
**Breakdown:**

• vendor.js: 600KB
• main.js: 400KB
• pages/dashboard.js: 200KB

**Fix:**
1. Dynamic import for dashboard: `const Dashboard = dynamic(() => import('./Dashboard'))`
2. Replace moment.js (300KB) with date-fns (30KB)
3. Enable tree shaking for lodash

### PERF-002: Unoptimized Images
**Files:**
- `public/hero.png` - 2.4MB
- `public/product-1.jpg` - 800KB
**Fix:**
1. Convert to WebP (80% smaller)
2. Add responsive sizes
3. Implement lazy loading

### PERF-003: N+1 Query in Dashboard
**File:** `src/pages/dashboard.tsx:45`
**Issue:** Fetching user data in loop
**Impact:** 100 users = 101 queries, ~2s load time
**Fix:** Use include/eager loading

## High Priority

### PERF-004: Missing React.memo on List Items
**File:** `src/components/ProductCard.tsx`
**Issue:** Re-renders on every parent render
**Impact:** Slow list scrolling
**Fix:**
```typescript
export const ProductCard = React.memo(({ product }) => {
  // ...
});

PERF-005: Inline Function in JSX

**File:** `src/components/Form.tsx:23` **Issue:** New function created every render

<button onClick={() => handleSubmit(data)}>  // Bad

**Fix:**

const onSubmit = useCallback(() => handleSubmit(data), [data]);
<button onClick={onSubmit}>  // Good

PERF-006: Missing Pagination

**File:** `src/api/products.ts:15` **Issue:** Fetching all 10,