ai-playbook 1.0.0

package/roles/software-developer/frontend/performance/best-practices.md

@@ -0,0 +1,350 @@
+# Performance: Best Practices
+
+Performance matters for user experience and business metrics. This guide covers how to identify bottlenecks and optimize strategically.
+
+## Measure First
+
+Never optimize without data. Measurement prevents wasting time on non-problems.
+
+```javascript
+// BAD: Premature optimization
+function Component() {
+  // Guess: rendering might be slow, so memoize
+  const expensiveCalculation = useMemo(() => {
+    return someSimpleArray.length;
+  }, [someSimpleArray]);
+  
+  // This optimization does nothing - adding complexity
+}
+
+// GOOD: Measure first, then optimize
+function Component() {
+  // Add monitoring
+  const startTime = performance.now();
+  
+  const result = expensiveCalculation(data);
+  
+  const duration = performance.now() - startTime;
+  if (duration > 100) {
+    console.warn(`Slow operation: ${duration}ms`);
+  }
+  
+  return <div>{result}</div>;
+}
+
+// Once you confirm it's slow, optimize:
+function Component() {
+  const result = useMemo(
+    () => expensiveCalculation(data),
+    [data]
+  );
+  
+  return <div>{result}</div>;
+}
+
+// Use Chrome DevTools Performance tab to identify bottlenecks
+// Use React DevTools Profiler to measure component render times
+```
+
+## Code Splitting
+
+Load code only when needed. This is especially important for large applications.
+
+```javascript
+// BAD: Single large bundle (e.g., 500KB)
+import AdminPanel from './admin/AdminPanel';
+import Dashboard from './dashboard/Dashboard';
+import Settings from './settings/Settings';
+
+function App() {
+  return user.isAdmin ? <AdminPanel /> : <Dashboard />;
+}
+// Downloads AdminPanel even if user is not admin
+
+// GOOD: Load admin panel only when needed
+import Dashboard from './dashboard/Dashboard';
+const AdminPanel = lazy(() => import('./admin/AdminPanel'));
+
+function App() {
+  return (
+    <Suspense fallback={<div>Loading...</div>}>
+      {user.isAdmin ? <AdminPanel /> : <Dashboard />}
+    </Suspense>
+  );
+}
+
+// Route-based code splitting (most effective)
+const Home = lazy(() => import('./pages/Home'));
+const About = lazy(() => import('./pages/About'));
+
+function App() {
+  return (
+    <Router>
+      <Suspense fallback={<div>Loading...</div>}>
+        <Routes>
+          <Route path="/" element={<Home />} />
+          <Route path="/about" element={<About />} />
+        </Routes>
+      </Suspense>
+    </Router>
+  );
+}
+```
+
+## Memoization When It Matters
+
+Only memoize when you have data showing the optimization helps.
+
+```javascript
+// BAD: Premature memoization
+const Button = React.memo(({ label }) => {
+  return <button>{label}</button>;
+});
+
+// GOOD: Memoize when:
+// 1. Receives objects/functions that change on every render
+// 2. Expensive render logic
+
+function Parent() {
+  const [count, setCount] = useState(0);
+  
+  // handleClick is recreated on every render
+  const handleClick = () => setCount(count + 1);
+  
+  // Passing new function to memoized child defeats the purpose
+  return <Button onClick={handleClick} label="Click" />;
+}
+
+// FIX: Use useCallback to maintain referential equality
+function Parent() {
+  const [count, setCount] = useState(0);
+  
+  const handleClick = useCallback(() => {
+    setCount(count + 1);
+  }, [count]);
+  
+  return (
+    <MemoButton onClick={handleClick} label="Click" />
+  );
+}
+
+const MemoButton = React.memo(({ onClick, label }) => {
+  return <button onClick={onClick}>{label}</button>;
+});
+```
+
+## Virtual Lists for Large Data
+
+Don't render thousands of items. Render only visible ones.
+
+```javascript
+// BAD: Render 10,000 items (browser freezes)
+function ItemList({ items }) {
+  return (
+    <ul>
+      {items.map(item => (
+        <li key={item.id}>{item.name}</li>
+      ))}
+    </ul>
+  );
+}
+
+const items = Array.from({ length: 10000 }, (_, i) => ({
+  id: i,
+  name: `Item ${i}`
+}));
+
+render(<ItemList items={items} />); // Freezes
+
+// GOOD: Virtual list (render only visible items)
+import { FixedSizeList } from 'react-window';
+
+function ItemList({ items }) {
+  return (
+    <FixedSizeList
+      height={600}
+      itemCount={items.length}
+      itemSize={35}
+      width="100%"
+    >
+      {({ index, style }) => (
+        <div style={style}>
+          {items[index].name}
+        </div>
+      )}
+    </FixedSizeList>
+  );
+}
+
+// With 10,000 items, only ~20 are rendered at a time
+```
+
+## API Response Caching
+
+Cache data to avoid redundant requests.
+
+```javascript
+// BAD: Refetch same data repeatedly
+function useUser(userId) {
+  const [user, setUser] = useState(null);
+  
+  useEffect(() => {
+    // Fetches even if userId hasn't changed
+    fetch(`/api/users/${userId}`)
+      .then(r => r.json())
+      .then(setUser);
+  }, [userId]); // Missing dependencies could cause issues
+  
+  return user;
+}
+
+// GOOD: Simple cache
+const userCache = new Map();
+
+function useUser(userId) {
+  const [user, setUser] = useState(null);
+  
+  useEffect(() => {
+    if (userCache.has(userId)) {
+      setUser(userCache.get(userId));
+      return;
+    }
+    
+    fetch(`/api/users/${userId}`)
+      .then(r => r.json())
+      .then(data => {
+        userCache.set(userId, data);
+        setUser(data);
+      });
+  }, [userId]);
+  
+  return user;
+}
+
+// BETTER: Cache with TTL
+function useCachedUser(userId, ttl = 5 * 60 * 1000) {
+  const [user, setUser] = useState(null);
+  
+  useEffect(() => {
+    const cached = userCache.get(userId);
+    if (cached && Date.now() - cached.timestamp < ttl) {
+      setUser(cached.data);
+      return;
+    }
+    
+    fetch(`/api/users/${userId}`)
+      .then(r => r.json())
+      .then(data => {
+        userCache.set(userId, { data, timestamp: Date.now() });
+        setUser(data);
+      });
+  }, [userId, ttl]);
+  
+  return user;
+}
+```
+
+## Network Optimization
+
+Minimize network requests and payload size.
+
+```javascript
+// BAD: Multiple requests
+function Dashboard() {
+  const [user, setUser] = useState(null);
+  const [stats, setStats] = useState(null);
+  const [settings, setSettings] = useState(null);
+  
+  useEffect(() => {
+    fetch('/api/user').then(r => r.json()).then(setUser);
+    fetch('/api/stats').then(r => r.json()).then(setStats);
+    fetch('/api/settings').then(r => r.json()).then(setSettings);
+  }, []);
+  // 3 requests when 1 would do
+}
+
+// GOOD: Single combined request
+function Dashboard() {
+  const [data, setData] = useState(null);
+  
+  useEffect(() => {
+    // Server returns combined data in one request
+    fetch('/api/dashboard').then(r => r.json()).then(setData);
+  }, []);
+  
+  return data ? (
+    <>
+      <User data={data.user} />
+      <Stats data={data.stats} />
+      <Settings data={data.settings} />
+    </>
+  ) : null;
+}
+
+// Use compression (gzip/brotli) - server config
+// Minimize payload size: only return necessary fields
+// Use image optimization: lazy load, responsive images
+```
+
+## Monitoring Performance
+
+Track performance in production.
+
+```javascript
+// Log Core Web Vitals
+function reportWebVitals() {
+  // Largest Contentful Paint
+  const observer = new PerformanceObserver((list) => {
+    const entries = list.getEntries();
+    const lastEntry = entries[entries.length - 1];
+    console.log('LCP:', lastEntry.startTime);
+  });
+  observer.observe({ entryTypes: ['largest-contentful-paint'] });
+  
+  // Cumulative Layout Shift
+  let cls = 0;
+  const clsObserver = new PerformanceObserver((list) => {
+    for (const entry of list.getEntries()) {
+      if (!entry.hadRecentInput) {
+        cls += entry.value;
+      }
+    }
+    console.log('CLS:', cls);
+  });
+  clsObserver.observe({ entryTypes: ['layout-shift'] });
+}
+
+// Track custom metrics
+function trackAPILatency(endpoint, duration) {
+  analytics.track('api_latency', {
+    endpoint,
+    duration_ms: duration,
+    timestamp: new Date().toISOString()
+  });
+  
+  // Alert if slow
+  if (duration > 1000) {
+    console.warn(`Slow API call: ${endpoint} took ${duration}ms`);
+  }
+}
+```
+
+## Performance Best Practices Checklist
+
+- [ ] Measured performance before optimizing
+- [ ] Code splitting used for large bundles
+- [ ] Memoization only applied where beneficial (with data)
+- [ ] Virtual lists used for large data sets
+- [ ] API responses cached appropriately
+- [ ] Unnecessary network requests eliminated
+- [ ] Images optimized and lazy-loaded
+- [ ] Bundle size monitored and controlled
+- [ ] Performance metrics tracked in production
+- [ ] No performance regressions introduced
+
+## Related Guidance
+
+- `/code-quality` — clean code that's easier to optimize  
+- `/debugging` — profiling and identifying bottlenecks  
+- `/tools-setup` — performance measurement tools  
+- `/logging-observability` — monitoring in production

package/roles/software-developer/frontend/state-management/README.md

@@ -0,0 +1,85 @@
+# State Management
+
+Senior frontend developers manage state predictably, minimize it, and make data flow explicit.
+
+## Core Principles
+
+- **Minimize State** — only what's necessary to render
+- **Explicit Flow** — clear data flow from source to consumer
+- **Immutability** — state changes create new objects, not mutations
+- **Single Source of Truth** — avoid duplicating state
+- **Predictability** — given same state + action, same result always
+
+## State Categories
+
+### Component State (Local)
+- Form inputs, UI toggles, modals
+- Use component state, hooks (useState)
+- Not shared across components
+- Simplest, preferred when isolated
+
+### Shared State (Global/Context)
+- Authentication, theme, user preferences
+- Shared across many components
+- Use context, state management libraries
+- Keep minimal, only truly global data
+
+### Server State (Remote)
+- Data from API, database
+- May be stale, needs sync
+- Separate from UI state
+- Cache invalidation critical
+
+### Derived State
+- Computed from other state (totals, filters)
+- Don't store separately; compute on demand
+- Reduces bugs from state inconsistency
+
+## State Management Patterns
+
+### Redux / Flux Pattern
+- Centralized store, actions, reducers
+- Predictable, debuggable
+- More boilerplate for simple cases
+- Good for complex apps with many interactions
+
+### Context API
+- Built-in React solution
+- Good for global UI state
+- Not ideal for frequently-changing data
+- Simpler than Redux for small state
+
+### Hooks (useState, useReducer, useContext)
+- Modern React approach
+- Manage local and shared state
+- Composable, reusable logic
+- Preferred for new code
+
+### External Libraries (Zustand, Jotai, Recoil)
+- Lighter than Redux
+- Less boilerplate
+- Good middle ground
+
+## Data Fetching & Caching
+
+- Fetch on mount, cache result
+- Refetch on demand (user action, interval)
+- Invalidate cache when data changes
+- Handle loading/error states explicitly
+- Consider libraries: React Query, SWR for this
+
+## Anti-Patterns
+
+- Prop drilling (pass through 3+ levels)
+- Duplicating state in multiple places
+- Storing derived state
+- Mutating state directly
+- Global state for everything
+- Race conditions in async state updates
+- Not handling error/loading states
+
+## Related Guidance
+
+- `/components` — how state flows through components
+- `/logging-observability` — tracking state changes
+- `/testing` — testing state mutations