gh-anton-abyzov-specweave-plugins-specweave-infrastructure/agents/sre/modules/ui-diagnostics.md

UI/Frontend Diagnostics

Purpose: Troubleshoot frontend performance, rendering, and user experience issues.

Common UI Issues

1. Slow Page Load

Symptoms:

• Users report long loading times
• Lighthouse score <50
• Time to Interactive (TTI) >5 seconds

Diagnosis:

Check Bundle Size

# Check JavaScript bundle size
ls -lh dist/*.js

# Analyze bundle composition
npx webpack-bundle-analyzer dist/stats.json

# Check for large dependencies
npm ls --depth=0

Red flags:

• Main bundle >500KB
• Unused dependencies in bundle
• Multiple copies of same library

Mitigation:

• Code splitting: import() for dynamic imports
• Tree shaking: Remove unused code
• Lazy loading: Load components on demand

---

Check Network Requests

# Chrome DevTools → Network tab
# Look for:
# - Number of requests (>100 = too many)
# - Large assets (images >200KB)
# - Slow API calls (>1s)

Red flags:

• Waterfall pattern (sequential loading)
• Large uncompressed images
• Blocking requests

Mitigation:

• Image optimization: WebP, lazy loading
• HTTP/2: Multiplexing
• CDN: Cache static assets

---

Check Render Performance

# Chrome DevTools → Performance tab
# Record page load, check:
# - Long tasks (>50ms)
# - Layout thrashing
# - JavaScript execution time

Red flags:

• Long tasks blocking main thread
• Multiple layout recalculations
• Heavy JavaScript computation

Mitigation:

• Web Workers: Move heavy computation off main thread
• requestIdleCallback: Defer non-critical work
• Virtual scrolling: Render only visible items

---

2. Memory Leak (UI)

Symptoms:

• Browser tab becomes slow over time
• Memory usage increases continuously
• Browser eventually crashes

Diagnosis:

Chrome DevTools → Memory

# Take heap snapshot before/after user interaction
# Compare snapshots
# Look for:
# - Detached DOM nodes
# - Event listeners not removed
# - Growing arrays/objects

Red flags:

• Detached DOM elements increasing
• Event listeners not garbage collected
• Timers/intervals not cleared

Mitigation:

// Clean up event listeners
componentWillUnmount() {
  element.removeEventListener('click', handler);
  clearInterval(this.intervalId);
  clearTimeout(this.timeoutId);
}

// Use WeakMap for DOM references
const cache = new WeakMap();

---

3. Unresponsive UI

Symptoms:

• Clicks don't register
• Input lag
• Frozen UI

Diagnosis:

Check Main Thread

# Chrome DevTools → Performance
# Look for:
# - Long tasks (>50ms)
# - Blocking JavaScript
# - Forced synchronous layout

Red flags:

• JavaScript blocking >100ms
• Synchronous XHR requests
• Layout thrashing (read → write → read)

Mitigation:

// Break up long tasks
async function processLargeArray(items) {
  for (let i = 0; i < items.length; i++) {
    await processItem(items[i]);

    // Yield to main thread every 100 items
    if (i % 100 === 0) {
      await new Promise(resolve => setTimeout(resolve, 0));
    }
  }
}

// Use requestIdleCallback
requestIdleCallback(() => {
  // Non-critical work
});

---

4. White Screen / Failed Render

Symptoms:

• Blank page
• Error boundary triggered
• Console errors

Diagnosis:

Check Console Errors

# Chrome DevTools → Console
# Look for:
# - Uncaught exceptions
# - Network errors (failed chunks)
# - CORS errors

Common causes:

• JavaScript error in render
• Failed to load chunk (code splitting)
• CORS blocking API calls
• Missing dependencies

Mitigation:

// Error boundary
class ErrorBoundary extends React.Component {
  componentDidCatch(error, errorInfo) {
    logErrorToService(error, errorInfo);
  }

  render() {
    if (this.state.hasError) {
      return <ErrorFallback />;
    }
    return this.props.children;
  }
}

// Retry failed chunk loads
const retryImport = (fn, retriesLeft = 3) => {
  return new Promise((resolve, reject) => {
    fn()
      .then(resolve)
      .catch(error => {
        if (retriesLeft === 0) {
          reject(error);
        } else {
          setTimeout(() => {
            retryImport(fn, retriesLeft - 1).then(resolve, reject);
          }, 1000);
        }
      });
  });
};

---

UI Performance Metrics

Core Web Vitals:

• LCP (Largest Contentful Paint): <2.5s (good), <4s (needs improvement), >4s (poor)
• FID (First Input Delay): <100ms (good), <300ms (needs improvement), >300ms (poor)
• CLS (Cumulative Layout Shift): <0.1 (good), <0.25 (needs improvement), >0.25 (poor)

Other Metrics:

• TTFB (Time to First Byte): <200ms
• FCP (First Contentful Paint): <1.8s
• TTI (Time to Interactive): <3.8s

Measurement:

// Web Vitals library
import {getLCP, getFID, getCLS} from 'web-vitals';

getLCP(console.log);
getFID(console.log);
getCLS(console.log);

---

Common UI Anti-Patterns

1. Render Everything Upfront

Problem: Rendering 10,000 items at once Solution: Virtual scrolling, pagination, infinite scroll

2. No Code Splitting

Problem: 5MB JavaScript bundle loaded upfront Solution: Route-based code splitting, lazy loading

3. Large Images

Problem: 5MB PNG images Solution: WebP, compression, lazy loading, responsive images

4. Blocking JavaScript

Problem: Heavy computation on main thread Solution: Web Workers, requestIdleCallback, async/await

5. Memory Leaks

Problem: Event listeners not removed, timers not cleared Solution: Cleanup in componentWillUnmount, WeakMap

---

UI Diagnostic Checklist

When diagnosing slow UI:

• Check bundle size (target: <500KB gzipped)
• Check number of network requests (target: <50)
• Check Core Web Vitals (LCP <2.5s, FID <100ms, CLS <0.1)
• Check for JavaScript errors in console
• Check render performance (no long tasks >50ms)
• Check memory usage (no continuous growth)
• Check for CORS errors
• Check for failed chunk loads
• Check image sizes (target: <200KB per image)
• Check for blocking resources

Tools:

• Chrome DevTools (Network, Performance, Memory, Console)
• Lighthouse
• Web Vitals library
• webpack-bundle-analyzer
• React DevTools Profiler

---

Related Documentation

• SKILL.md - Main SRE agent
• backend-diagnostics.md - Backend troubleshooting
• monitoring.md - Observability tools