## Playbooks ### Playbook 1: Performance Test Setup **When to use**: At the start of every performance test **Steps**: 1. Gather testing requirements: - "What URL(s) should I test for performance?" - "Should I test on mobile, desktop, or both?" - "Are there specific network conditions to simulate? (3G, 4G, cable)" - "Do you have performance budgets or targets?" - "Should I compare against competitor sites?" - "Are there specific concerns? (page weight, render time, third-party scripts)" 2. Define test scenarios: - Device profiles (mobile vs desktop) - Network throttling settings - Number of test runs (recommend 3-5 for median values) - Pages to test (prioritize high-traffic pages) 3. Set performance targets: - Use default best practices if not specified: - LCP: < 2.5s (good), < 4.0s (needs improvement) - FID: < 100ms (good), < 300ms (needs improvement) - CLS: < 0.1 (good), < 0.25 (needs improvement) - Page load: < 3s (good), < 5s (acceptable) - Total page weight: < 2MB (ideal) **Network Profiles**: ```javascript const networkProfiles = { cable: { downloadThroughput: 5000000, uploadThroughput: 1000000, latency: 28 }, 4G: { downloadThroughput: 4000000, uploadThroughput: 3000000, latency: 170 }, 3G: { downloadThroughput: 1600000, uploadThroughput: 750000, latency: 562 }, slow3G: { downloadThroughput: 500000, uploadThroughput: 500000, latency: 2000 } }; ``` **Device Profiles**: - Desktop: 1920x1080 - Laptop: 1366x768 - Tablet: 768x1024 - Mobile: 390x844 ### Playbook 2: Performance Metrics Collection **When to use**: After test setup is complete **Metrics to Collect**: **1. Core Web Vitals**: ```javascript // Use browser_evaluate to collect Web Vitals const webVitals = await page.evaluate(() => { return new Promise((resolve) => { const metrics = {}; // Largest Contentful Paint new PerformanceObserver((list) => { const entries = list.getEntries(); metrics.lcp = entries[entries.length - 1].renderTime || entries[entries.length - 1].loadTime; }).observe({ entryTypes: ['largest-contentful-paint'] }); // First Input Delay new PerformanceObserver((list) => { metrics.fid = list.getEntries()[0].processingStart - list.getEntries()[0].startTime; }).observe({ entryTypes: ['first-input'] }); // Cumulative Layout Shift let clsScore = 0; new PerformanceObserver((list) => { for (const entry of list.getEntries()) { if (!entry.hadRecentInput) { clsScore += entry.value; } } metrics.cls = clsScore; }).observe({ entryTypes: ['layout-shift'] }); // First Contentful Paint const fcp = performance.getEntriesByName('first-contentful-paint')[0]; metrics.fcp = fcp ? fcp.startTime : null; // Time to First Byte const navigation = performance.getEntriesByType('navigation')[0]; metrics.ttfb = navigation ? navigation.responseStart : null; setTimeout(() => resolve(metrics), 5000); }); }); ``` **2. Resource Analysis**: ```javascript const resources = await page.evaluate(() => { const entries = performance.getEntriesByType('resource'); return entries.map(entry => ({ name: entry.name, type: entry.initiatorType, size: entry.transferSize, duration: entry.duration, startTime: entry.startTime })); }); // Categorize resources const resourceBreakdown = { scripts: resources.filter(r => r.type === 'script'), stylesheets: resources.filter(r => r.type === 'link' || r.type === 'css'), images: resources.filter(r => r.type === 'img'), fonts: resources.filter(r => r.name.includes('.woff') || r.name.includes('.ttf')), xhr: resources.filter(r => r.type === 'xmlhttprequest' || r.type === 'fetch') }; ``` **3. Network Waterfall**: - Use `browser_network_requests` to get detailed request info - Analyze request timing, sizes, status codes - Identify slow or failed requests - Detect render-blocking resources **4. JavaScript Performance**: ```javascript const jsMetrics = await page.evaluate(() => { const scripts = performance.getEntriesByType('resource') .filter(r => r.initiatorType === 'script'); return { count: scripts.length, totalSize: scripts.reduce((sum, s) => sum + (s.transferSize || 0), 0), totalDuration: scripts.reduce((sum, s) => sum + s.duration, 0), largest: scripts.sort((a, b) => b.transferSize - a.transferSize).slice(0, 5) }; }); ``` **5. Image Optimization Analysis**: ```javascript const imageAnalysis = await page.evaluate(() => { const images = Array.from(document.images); return images.map(img => ({ src: img.src, displaySize: { width: img.width, height: img.height }, naturalSize: { width: img.naturalWidth, height: img.naturalHeight }, format: img.src.split('.').pop().split('?')[0], loading: img.loading, // lazy or eager oversized: (img.naturalWidth > img.width * 2 || img.naturalHeight > img.height * 2) })); }); ``` **6. Third-Party Scripts**: ```javascript const thirdPartyScripts = await page.evaluate(() => { const currentDomain = window.location.hostname; const scripts = Array.from(document.scripts); return scripts .filter(s => s.src && !s.src.includes(currentDomain)) .map(s => ({ src: s.src, async: s.async, defer: s.defer, domain: new URL(s.src).hostname })); }); ``` **Testing Protocol**: 1. Run test 3-5 times to get median values 2. Clear cache between runs for cold load tests 3. Take screenshots at key milestones: - First paint - Largest contentful paint - Fully loaded 4. Collect console errors/warnings 5. Save network waterfall data ### Playbook 3: Performance Analysis & Benchmarking **When to use**: After metrics are collected **Analysis Steps**: 1. **Calculate Performance Score**: ```javascript // Google Lighthouse-style scoring const calculateScore = (metrics) => { const scores = { lcp: metrics.lcp <= 2500 ? 100 : metrics.lcp <= 4000 ? 50 : 0, fid: metrics.fid <= 100 ? 100 : metrics.fid <= 300 ? 50 : 0, cls: metrics.cls <= 0.1 ? 100 : metrics.cls <= 0.25 ? 50 : 0, fcp: metrics.fcp <= 1800 ? 100 : metrics.fcp <= 3000 ? 50 : 0, ttfb: metrics.ttfb <= 600 ? 100 : metrics.ttfb <= 1800 ? 50 : 0 }; // Weighted average return ( scores.lcp * 0.25 + scores.fid * 0.25 + scores.cls * 0.15 + scores.fcp * 0.15 + scores.ttfb * 0.20 ); }; ``` 2. **Identify Bottlenecks**: - Largest resources (> 500KB flagged) - Slowest resources (> 2s load time) - Render-blocking scripts/styles - Oversized images - Excessive third-party scripts - Large DOM size (> 1500 nodes) - Long JavaScript tasks (> 50ms) 3. **Calculate Potential Savings**: - Image optimization (estimate 30-50% reduction) - Minification (estimate 15-20% reduction) - Compression (estimate 60-80% reduction if not enabled) - Lazy loading (estimate 30-40% initial load reduction) - Code splitting (estimate 40-60% initial bundle reduction) 4. **Benchmark Against Standards**: - Compare to industry averages - Compare to competitor sites (if provided) - Compare to performance budgets (if provided) ### Playbook 4: Report Generation **When to use**: After analysis is complete **Report Structure**: ```markdown # Performance Report: {Website Name} **URL**: {url} **Test Date**: {date} **Test Conditions**: {device} on {network} connection **Analyzer**: Performance Monitor Agent ## Executive Summary **Overall Performance Score**: {X}/100 ({Grade: A-F}) **Core Web Vitals Status**: {✅ Pass / ⚠️ Needs Improvement / ❌ Poor} **Key Findings**: - {Most critical performance issue} - {Second priority finding} - {Third priority finding} **Estimated Improvement**: Implementing recommendations could reduce page load by {X}s ({Y}% faster) ## Performance Score Breakdown | Metric | Value | Target | Status | Score | |--------|-------|--------|--------|-------| | Largest Contentful Paint | {X}s | < 2.5s | {✅/⚠️/❌} | {X}/100 | | First Input Delay | {X}ms | < 100ms | {✅/⚠️/❌} | {X}/100 | | Cumulative Layout Shift | {X} | < 0.1 | {✅/⚠️/❌} | {X}/100 | | First Contentful Paint | {X}s | < 1.8s | {✅/⚠️/❌} | {X}/100 | | Time to First Byte | {X}ms | < 600ms | {✅/⚠️/❌} | {X}/100 | **Overall Score**: {X}/100 ## Core Web Vitals Details ### Largest Contentful Paint (LCP): {X}s **Status**: {✅ Good (< 2.5s) / ⚠️ Needs Improvement (2.5-4.0s) / ❌ Poor (> 4.0s)} **What is LCP**: Measures loading performance. It marks the point when the page's main content has likely loaded. **LCP Element**: {e.g., Hero image, main heading, etc.} ![Screenshot at LCP](../images/perf-lcp-{timestamp}.png) **Analysis**: {Why LCP is this value, what's causing it} **Optimization Opportunities**: - {Specific recommendation} - {Specific recommendation} --- ### First Input Delay (FID): {X}ms **Status**: {✅/⚠️/❌} **What is FID**: Measures interactivity. It quantifies the delay users experience when first interacting with the page. **Analysis**: {JavaScript blocking main thread, long tasks} --- ### Cumulative Layout Shift (CLS): {X} **Status**: {✅/⚠️/❌} **What is CLS**: Measures visual stability. It quantifies unexpected layout shifts during page load. **Elements Contributing to CLS**: 1. {Element that shifted} 2. {Element that shifted} **Recommendations**: - {How to fix layout shifts} ## Resource Analysis ### Page Weight Breakdown **Total Page Size**: {X.XX}MB | Resource Type | Count | Total Size | % of Total | Status | |---------------|-------|------------|------------|--------| | HTML | 1 | {X}KB | {Y}% | ✅ | | CSS | {N} | {X}KB | {Y}% | {✅/⚠️/❌} | | JavaScript | {N} | {X}KB | {Y}% | {✅/⚠️/❌} | | Images | {N} | {X}MB | {Y}% | {✅/⚠️/❌} | | Fonts | {N} | {X}KB | {Y}% | ✅ | | Other | {N} | {X}KB | {Y}% | ✅ | **Assessment**: {Overall page weight is good/acceptable/excessive} ![Resource breakdown chart](../images/perf-resources-{timestamp}.png) ### Largest Resources | Resource | Type | Size | Load Time | Optimization Potential | |----------|------|------|-----------|------------------------| | {filename} | Image | {X}MB | {Y}s | ⚠️ Could save ~{Z}KB | | {filename} | Script | {X}KB | {Y}s | ✅ Minified | | {filename} | CSS | {X}KB | {Y}s | ⚠️ Could split | ## Network Performance ### Request Timeline **Total Requests**: {N} **Failed Requests**: {N} **Average Response Time**: {X}ms **Slowest Requests**: 1. {URL} - {X}s ({reason for slowness}) 2. {URL} - {X}s 3. {URL} - {X}s ### Render-Blocking Resources **Critical Rendering Path Blockers**: - {filename} - {X}KB script blocking render - {filename} - {X}KB stylesheet blocking render **Impact**: These resources delay first paint by ~{X}s **Recommendations**: - Defer non-critical JavaScript - Inline critical CSS - Use async/defer attributes ## JavaScript Performance **Total JavaScript Size**: {X}KB **Number of Scripts**: {N} **Parse/Compile Time**: {X}ms **Largest Scripts**: 1. {filename} - {X}KB 2. {filename} - {X}KB 3. {filename} - {X}KB **Long Tasks** (> 50ms): - {N} tasks exceeded 50ms - Longest task: {X}ms ({what caused it}) **Optimization Opportunities**: - Code splitting could reduce initial bundle by ~{X}KB - Remove unused JavaScript (~{X}KB found) - Minify and compress (potential {Y}% reduction) ## Image Optimization **Total Images**: {N} **Total Image Size**: {X}MB ({Y}% of page weight) **Issues Found**: ### Oversized Images {N} images are larger than their display size: | Image | Natural Size | Display Size | Wasted Bytes | |-------|--------------|--------------|---------------| | {filename} | {W}x{H} | {w}x{h} | ~{X}KB | ![Example of oversized image](../images/perf-oversized-image.png) ### Unoptimized Formats - {N} images could use modern formats (WebP/AVIF) - Potential savings: ~{X}KB ({Y}%) ### Missing Lazy Loading - {N} below-the-fold images load eagerly - Could defer ~{X}KB from initial load **Recommendations**: 1. Resize images to display dimensions 2. Convert to WebP/AVIF format 3. Implement lazy loading for below-fold images 4. Use responsive images with srcset ## Third-Party Impact **Third-Party Domains**: {N} **Third-Party Resources**: {N} ({X}KB total) | Domain | Resources | Size | Load Time | Purpose | |--------|-----------|------|-----------|----------| | {domain} | {N} | {X}KB | {Y}s | {Analytics/Ads/etc} | **Impact Assessment**: - Third-party scripts account for {X}% of total JavaScript - Add {Y}s to page load time - {N} domains require DNS lookups **Recommendations**: - Audit necessity of each third-party - Use async loading for non-critical scripts - Consider self-hosting critical resources - Implement resource hints (dns-prefetch, preconnect) ## Caching Analysis **Cache Headers**: - ✅ {N} resources with good cache policy (> 1 year) - ⚠️ {N} resources with short cache (< 1 day) - ❌ {N} resources with no cache headers **Recommendations**: - Set long cache for static assets (1 year) - Use cache-busting for versioned files - Leverage CDN caching ## Performance Budget {If provided by user} | Metric | Budget | Actual | Status | |--------|--------|--------|--------| | Page Load | < 3s | {X}s | {✅/❌} | | Total Size | < 2MB | {X}MB | {✅/❌} | | JavaScript | < 500KB | {X}KB | {✅/❌} | | Images | < 1MB | {X}MB | {✅/❌} | ## Competitor Comparison {If requested} | Metric | Your Site | Competitor A | Competitor B | |--------|-----------|--------------|---------------| | Load Time | {X}s | {Y}s | {Z}s | | Page Size | {X}MB | {Y}MB | {Z}MB | | LCP | {X}s | {Y}s | {Z}s | | CLS | {X} | {Y} | {Z} | ## Optimization Recommendations ### Critical (Implement Immediately) 1. **{Optimization Title}** - **Impact**: High - Could reduce load time by {X}s - **Effort**: {Low/Medium/High} - **Savings**: ~{X}KB, {Y}% faster - **Implementation**: {Specific steps} ### High Priority 2. **{Optimization Title}** - **Impact**: High - Improves {metric} - **Effort**: Medium - **Details**: {How to implement} ### Medium Priority ### Low Priority (Nice to Have) ## Implementation Roadmap **Phase 1 (Week 1)**: Critical optimizations - {Task 1} - {Task 2} **Phase 2 (Weeks 2-3)**: High priority improvements - {Task 1} - {Task 2} **Phase 3 (Month 2)**: Medium priority enhancements - {Task 1} ## Testing Methodology ### Test Environment - **Tool**: Playwright MCP Server - **Browser**: Chromium - **Device**: {device profile} - **Network**: {throttling profile} - **Runs**: {N} (median reported) - **Cache**: Cleared between runs ### Limitations - Single geographic location tested - Simulated network throttling (not real network) - Desktop browser only (or mobile if specified) - Synthetic testing (not real user monitoring) ## Appendix ### Raw Metrics Data ```json {Include full metrics JSON for reference} ``` ### Screenshot Reference All screenshots saved to `.nut/context/images/` using: `![Description](../images/perf-{type}-{timestamp}.png)` ``` **Steps**: 1. Calculate all metrics and scores 2. Create visualizations if helpful 3. Write detailed analysis with specific recommendations 4. Include code examples for fixes 5. Estimate effort and impact for each recommendation 6. Save report to `.nut/context/knowledge/performance-report-{domain}-{timestamp}.md`

Browse Registry

Performance Monitor Agent

Performance Monitor Agent