rdfitted/perf-audit

Code + Live Performance Review

Combines static code analysis for reflow-triggering patterns with Google Lighthouse CLI for real-world performance metrics. Identifies where @chenglou/pretext adoption would improve Core Web Vitals.

Arguments (via args string)

• First positional arg: Preview/staging URL to run Lighthouse against (optional)
• --static-only: Skip Lighthouse, only run static analysis
• --lighthouse-only: Skip static analysis, only run Lighthouse against URL

Workflow

Step 1: Static Analysis — Reflow Hotspots

Scan for patterns that trigger browser layout reflow, categorized by severity:

Critical Reflow Triggers (force synchronous layout)

Grep patterns across *.{js,ts,jsx,tsx}:
- getBoundingClientRect
- offset(Top|Left|Width|Height)
- scroll(Top|Left|Width|Height)  
- client(Top|Left|Width|Height)
- getComputedStyle
- innerText (triggers reflow to compute text)
- window\.getSelection

Layout Thrashing Patterns (read-then-write in loops)

Search for patterns where DOM reads and writes alternate:

- for/while loops containing both reads (offset*, getBounding*) and writes (style.*, className, innerHTML)
- Array.forEach/map with DOM measurement inside
- requestAnimationFrame with measurement + mutation

Text-Specific Reflow Patterns

- measureText without Pretext
- font-loading callbacks that trigger re-measurement
- ResizeObserver on text containers
- Dynamic font-size calculations
- Text truncation via JS (measuring then cutting)
- Virtualized list height estimation via DOM

For each finding, read 10 lines of context to classify:

• HOT PATH: Called frequently (in loops, scroll handlers, resize handlers, render cycles)
• COLD PATH: Called once (initialization, rare events)
• PRETEXT-REPLACEABLE: Text measurement that Pretext's prepare()/layout() could handle

Step 2: Lighthouse CLI Audit (if URL provided)

# Check if Lighthouse is available
npx lighthouse --version 2>/dev/null || npm install -g lighthouse

# Run Lighthouse with performance focus
npx lighthouse "{URL}" \
  --output=json \
  --output-path=./lighthouse-report.json \
  --chrome-flags="--headless --no-sandbox" \
  --only-categories=performance \
  --throttling-method=simulate \
  --preset=desktop

# Also run mobile
npx lighthouse "{URL}" \
  --output=json \
  --output-path=./lighthouse-report-mobile.json \
  --chrome-flags="--headless --no-sandbox" \
  --only-categories=performance \
  --throttling-method=simulate \
  --preset=perf

Extract key metrics from JSON:

• LCP (Largest Contentful Paint) — text rendering speed
• CLS (Cumulative Layout Shift) — layout stability (Pretext's sweet spot)
• TBT (Total Blocking Time) — main thread blocking from reflow
• FCP (First Contentful Paint)
• SI (Speed Index)
• TTI (Time to Interactive)

Also extract:

• Specific audit failures related to layout shift
• "Avoid large layout shifts" diagnostics
• "Reduce unused JavaScript" (potential dead measurement code)
• "Avoid an excessive DOM size" warnings

Step 3: Pretext Impact Assessment

Cross-reference static findings with Lighthouse results:

| Finding | Static Analysis | Lighthouse Impact | Pretext Fix | |---------|----------------|-------------------|-------------| | Text height measurement in virtualized list | getBoundingClientRect in scroll handler (HOT) | High CLS, High TBT | Replace with prepare() + layout() | | Font-size responsive calculation | getComputedStyle in resize handler (HOT) | Medium CLS | Use prepare() per breakpoint, layout() on resize | | Text truncation check | scrollHeight comparison (COLD) | Low impact | Optional — low priority |

Step 4: Run pretext-check

Invoke the pretext-check skill to get current dependency status:

Skill(skill="pretext-check")

Merge those findings into the overall report.

Step 5: Report

## Performance Audit Report

### Lighthouse Scores (if URL provided)
| Metric | Desktop | Mobile | Target |
|--------|---------|--------|--------|
| Performance | XX | XX | >90 |
| LCP | X.Xs | X.Xs | <2.5s |
| CLS | X.XX | X.XX | <0.1 |
| TBT | XXms | XXms | <200ms |
| FCP | X.Xs | X.Xs | <1.8s |
| TTI | X.Xs | X.Xs | <3.8s |

### Static Analysis Summary
- **X** critical reflow triggers found
- **Y** layout thrashing patterns found  
- **Z** text-specific patterns (Pretext-replaceable)
- **W** hot-path patterns (highest impact)

### Pretext Integration Opportunities

#### High Impact (Hot Path + Pretext-Replaceable)
1. `file:line` — Description — Est. CLS improvement: X.XX
2. ...

#### Medium Impact (Cold Path or Partial Replacement)
1. `file:line` — Description
2. ...

#### Low Impact (Optional / Future)
1. `file:line` — Description
2. ...

### Pretext Dependency Status
{output from pretext-check skill}

### Action Items
- [ ] Install @chenglou/pretext (if not installed)
- [ ] Replace N hot-path text measurements with Pretext
- [ ] Re-run /perf-audit after changes to measure improvement
- [ ] Target CLS < 0.1, TBT < 200ms

### Estimated Impact
- CLS improvement: ~X.XX (from removing N reflow-triggering text measurements)
- TBT improvement: ~XXms (from eliminating synchronous layout in hot paths)

Step 6: Save Report

Save the full report to the project:

Write report to: .ai-docs/perf-audit-{date}.md

If .ai-docs/ doesn't exist, save to project root as perf-audit-{date}.md.

Clean up Lighthouse JSON files after extracting data.

Integration Notes

This skill is invoked by:

• /build — after implementation, as part of Phase 3 validation (if frontend changes detected)
• /scope — during Phase 2 scouting, to baseline current performance before planning changes
• /kickoff — during Phase 2, if an existing frontend project is being extended

When called from another command, return a condensed summary for inclusion.