ai-playbook 1.0.0

package/roles/software-developer/frontend/logging-observability/best-practices.md

@@ -0,0 +1,430 @@
+# Logging & Observability: Best Practices
+
+Good logging and observability let you understand what's happening in production. This guide covers what to log, how to structure logs, and how to make them actionable.
+
+## Structured Logging
+
+Structured logs are parseable and queryable, unlike free-form text.
+
+```javascript
+// BAD: Unstructured logging (hard to search/analyze)
+console.log('User clicked button');
+console.log('API request took 234ms');
+console.log('Error loading data');
+
+// GOOD: Structured logging
+console.log(JSON.stringify({
+  event: 'button_clicked',
+  timestamp: new Date().toISOString(),
+  user_id: 123,
+  button_name: 'save'
+}));
+
+console.log(JSON.stringify({
+  event: 'api_request_completed',
+  timestamp: new Date().toISOString(),
+  endpoint: '/api/users/123',
+  duration_ms: 234,
+  status: 200
+}));
+
+console.error(JSON.stringify({
+  event: 'api_request_failed',
+  timestamp: new Date().toISOString(),
+  endpoint: '/api/users/123',
+  error_message: 'Network timeout',
+  error_code: 'NETWORK_TIMEOUT'
+}));
+
+// With structured logs, you can:
+// - Filter: all events where user_id = 123
+// - Aggregate: average duration_ms by endpoint
+// - Alert: when error_count > 10 in 5 minutes
+```
+
+## Log Levels
+
+Use the right level for each log message.
+
+```javascript
+// DEBUG: Low-level technical information
+// - Variable values during development
+// - Function entry/exit
+// - Detailed state changes
+// Only visible in development or with DEBUG flag enabled
+
+logger.debug({
+  event: 'user_data_loaded',
+  user: user,
+  timestamp: new Date().toISOString()
+});
+
+// INFO: Notable business events
+// - User actions (login, purchase, post created)
+// - API calls completed successfully
+// - Configuration loaded
+
+logger.info({
+  event: 'user_logged_in',
+  user_id: 123,
+  timestamp: new Date().toISOString()
+});
+
+// WARN: Unexpected but recoverable situations
+// - Deprecated API usage
+// - Slow operations (exceeded threshold)
+// - Falling back to default behavior
+
+logger.warn({
+  event: 'api_call_slow',
+  endpoint: '/api/users',
+  duration_ms: 3500,
+  threshold_ms: 1000
+});
+
+// ERROR: Errors that need attention
+// - API calls failed
+// - Data validation failed
+// - Unhandled exceptions
+// - Should be reviewed and fixed
+
+logger.error({
+  event: 'api_call_failed',
+  endpoint: '/api/users/123',
+  status: 500,
+  error: 'Server error'
+});
+
+// CRITICAL/FATAL: System down
+// - Service unavailable
+// - Data corruption detected
+// - Need immediate human intervention
+
+logger.critical({
+  event: 'database_connection_lost',
+  duration_sec: 30,
+  attempt: 5
+});
+```
+
+## What to Log
+
+Log the right things to understand what's happening.
+
+```javascript
+// DO: Log user actions and business events
+logger.info({
+  event: 'user_action',
+  action: 'create_post',
+  user_id: user.id,
+  post_id: post.id,
+  timestamp: new Date().toISOString()
+});
+
+// DO: Log data flow - input and output
+function processPayment(payment) {
+  logger.debug({
+    event: 'process_payment_start',
+    payment_id: payment.id,
+    amount: payment.amount
+  });
+  
+  const result = chargeCard(payment);
+  
+  logger.info({
+    event: 'process_payment_success',
+    payment_id: payment.id,
+    transaction_id: result.id
+  });
+  
+  return result;
+}
+
+// DO: Log errors with context
+function handleError(error, context) {
+  logger.error({
+    event: 'error_occurred',
+    error_message: error.message,
+    error_code: error.code,
+    stack_trace: error.stack,
+    context: context,
+    timestamp: new Date().toISOString()
+  });
+}
+
+// DO: Log performance metrics
+function measure(name, fn) {
+  const start = performance.now();
+  const result = fn();
+  const duration = performance.now() - start;
+  
+  logger.info({
+    event: 'operation_completed',
+    operation: name,
+    duration_ms: duration
+  });
+  
+  return result;
+}
+
+// DO NOT: Log secrets
+logger.info({
+  event: 'user_auth',
+  // DON'T log password
+  user_id: user.id,
+  // DON'T log full token
+  token_prefix: token.substring(0, 10)
+});
+
+// DO NOT: Log sensitive personal data
+logger.info({
+  // Don't log full SSN
+  user_id: user.id,
+  // Don't log full credit card
+  payment_method: 'card_****_****_****_4242'
+});
+
+// DO NOT: Log excessive data
+logger.info({
+  // Don't log entire user object if you only need ID
+  user_id: user.id,
+  action: 'login'
+});
+```
+
+## Never Log Secrets
+
+This is critical. Secrets in logs are security breaches.
+
+```javascript
+// BAD: Secrets logged (CRITICAL BUG)
+const apiKey = process.env.API_KEY;
+logger.debug('Using API key:', apiKey); // SECURITY ISSUE
+
+const token = getAuthToken();
+logger.info('Auth token:', token); // SECURITY ISSUE
+
+// GOOD: Log only identifiers or placeholders
+const apiKey = process.env.API_KEY;
+logger.debug('API client initialized'); // No key logged
+
+const token = getAuthToken();
+logger.info({
+  event: 'authentication_success',
+  user_id: decodeToken(token).userId
+}); // No token logged
+
+// Sanitize logs before sending to external service
+function sanitizeLog(obj) {
+  const sanitized = { ...obj };
+  
+  // Remove common secret fields
+  delete sanitized.password;
+  delete sanitized.token;
+  delete sanitized.api_key;
+  delete sanitized.secret;
+  delete sanitized.private_key;
+  
+  // Mask sensitive patterns
+  if (sanitized.credit_card) {
+    sanitized.credit_card = sanitized.credit_card.replace(/\d(?=\d{4})/g, '*');
+  }
+  
+  return sanitized;
+}
+
+// IMPORTANT: Audit logs regularly
+// Check production logs for secrets that leaked
+// If found, rotate that credential immediately
+```
+
+## Request IDs (Correlation IDs)
+
+Track requests across multiple services for easier debugging.
+
+```javascript
+// Generate request ID
+function generateRequestId() {
+  return `${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+}
+
+// Pass through entire request lifecycle
+function makeRequest(url, options = {}) {
+  const requestId = generateRequestId();
+  
+  logger.info({
+    event: 'http_request_start',
+    request_id: requestId,
+    method: options.method || 'GET',
+    url: url
+  });
+  
+  return fetch(url, {
+    ...options,
+    headers: {
+      ...options.headers,
+      'X-Request-ID': requestId
+    }
+  })
+    .then(r => {
+      logger.info({
+        event: 'http_request_success',
+        request_id: requestId,
+        status: r.status,
+        duration_ms: Date.now() - parseInt(requestId)
+      });
+      return r;
+    })
+    .catch(err => {
+      logger.error({
+        event: 'http_request_failed',
+        request_id: requestId,
+        error_message: err.message
+      });
+      throw err;
+    });
+}
+
+// Include request_id in ALL logs within that request
+function Component({ userId }) {
+  const [requestId] = useState(generateRequestId());
+  
+  useEffect(() => {
+    logger.info({
+      request_id: requestId,
+      event: 'component_mounted',
+      user_id: userId
+    });
+  }, [userId, requestId]);
+}
+
+// Benefits: Can trace entire request flow across frontend and backend
+```
+
+## Error Reporting
+
+Capture errors automatically and report them.
+
+```javascript
+// Global error handler
+window.addEventListener('error', (event) => {
+  logger.error({
+    event: 'uncaught_error',
+    error_message: event.error?.message,
+    error_stack: event.error?.stack,
+    filename: event.filename,
+    lineno: event.lineno,
+    colno: event.colno,
+    timestamp: new Date().toISOString()
+  });
+  
+  // Send to error tracking service
+  reportToSentry({
+    message: event.error?.message,
+    stack: event.error?.stack
+  });
+});
+
+// Promise rejection handler
+window.addEventListener('unhandledrejection', (event) => {
+  logger.error({
+    event: 'unhandled_rejection',
+    reason: event.reason?.message,
+    stack: event.reason?.stack,
+    timestamp: new Date().toISOString()
+  });
+  
+  reportToSentry({
+    message: event.reason?.message,
+    stack: event.reason?.stack
+  });
+});
+
+// React error boundary
+class ErrorBoundary extends React.Component {
+  componentDidCatch(error, errorInfo) {
+    logger.error({
+      event: 'react_error_boundary',
+      error_message: error.toString(),
+      component_stack: errorInfo.componentStack
+    });
+    
+    reportToSentry({
+      message: error.toString(),
+      stack: errorInfo.componentStack
+    });
+  }
+  
+  render() {
+    if (this.state.hasError) {
+      return <div>Something went wrong. Error has been reported.</div>;
+    }
+    return this.props.children;
+  }
+}
+```
+
+## Logging Cleanup
+
+Keep logs clean and manageable.
+
+```javascript
+// BAD: Console.log left in production
+function Component() {
+  const [data, setData] = useState(null);
+  
+  useEffect(() => {
+    fetchData()
+      .then(data => {
+        console.log('DATA:', data); // Should be removed
+        setData(data);
+      });
+  }, []);
+}
+
+// GOOD: Use logger levels appropriately
+function Component() {
+  const [data, setData] = useState(null);
+  
+  useEffect(() => {
+    fetchData()
+      .then(data => {
+        logger.debug({ event: 'data_loaded', data }); // Only in debug mode
+        setData(data);
+      });
+  }, []);
+}
+
+// Remove debug logs before shipping to production
+// Use environment variables to control log level
+const logLevel = process.env.LOG_LEVEL || 'info';
+
+const logger = {
+  debug: logLevel === 'debug' ? console.log : () => {},
+  info: console.log,
+  warn: console.warn,
+  error: console.error
+};
+```
+
+## Logging & Observability Checklist
+
+- [ ] Using structured logging (JSON, not free-form text)
+- [ ] Using appropriate log levels (DEBUG, INFO, WARN, ERROR)
+- [ ] Logging user actions and business events
+- [ ] Logging errors with full context
+- [ ] NO secrets logged (passwords, tokens, keys)
+- [ ] NO sensitive PII logged (full SSN, full CC, email if avoidable)
+- [ ] Using request IDs for tracing
+- [ ] Error tracking service configured
+- [ ] Global error handlers in place
+- [ ] Debug logs removed before production
+- [ ] Log retention/cleanup policy defined
+- [ ] Monitoring alerts configured for ERROR level
+
+## Related Guidance
+
+- `/debugging` — using logs to debug issues  
+- `/code-quality` — clean logging patterns  
+- `/tools-setup` — logging libraries and services  
+- `/performance` — monitoring performance metrics

package/roles/software-developer/frontend/performance/README.md

@@ -0,0 +1,99 @@
+# Performance
+
+Senior frontend developers measure performance, identify bottlenecks, and optimize strategically.
+
+## Measurement First
+
+- **Never optimize blindly** — measure before and after
+- **Use real metrics** — Lab (synthetic) and Field (real users)
+- **Identify bottleneck** — not all optimizations have same impact
+
+### Key Metrics
+
+- **First Contentful Paint (FCP)** — when first content appears
+- **Largest Contentful Paint (LCP)** — when main content visible
+- **Cumulative Layout Shift (CLS)** — visual stability
+- **Time to Interactive (TTI)** — when page is interactive
+- **Bundle Size** — total JS/CSS sent to user
+
+### Tools
+
+- Chrome DevTools (Performance tab)
+- Lighthouse (automated audits)
+- WebPageTest (detailed analysis)
+- Web Vitals library (field metrics)
+
+## Common Optimizations
+
+### Code Splitting
+- Load only what's needed initially
+- Lazy load components (React.lazy)
+- Route-based splitting (load page code on navigation)
+- Reduces initial bundle size
+
+### Memoization
+- `React.memo` — skip re-render if props unchanged
+- `useMemo` — cache expensive computations
+- `useCallback` — cache function references
+- Use when dependencies are stable
+
+### Rendering Optimization
+- Virtual lists (render visible items only)
+- Windowing for large lists
+- Pagination for data-heavy pages
+- Reduces DOM nodes and memory
+
+### Network Optimization
+- Cache API responses
+- Use CDN for static assets
+- Minify CSS/JS/HTML
+- Gzip compression
+- HTTP/2 multiplexing
+
+### Image Optimization
+- Use appropriate formats (WebP, AVIF, JPEG)
+- Lazy load images
+- Responsive images (srcset)
+- Compress without quality loss
+
+## React-Specific Patterns
+
+- Avoid large re-renders with context splitting
+- Use Suspense for code splitting
+- Profile with React DevTools Profiler
+- Check render count (Profiler tab)
+- Identify slow components
+
+## Monitoring in Production
+
+- Track Core Web Vitals
+- Monitor error rates
+- Track performance over time
+- Alert on regressions
+- Use analytics to correlate performance with user behavior
+
+## Anti-Patterns
+
+- Premature optimization (optimize without data)
+- Over-memoization (adds complexity, minimal gain)
+- Excessive state mutations
+- Not lazy loading anything
+- Ignoring bundle size
+- No caching strategy
+- Optimizing wrong metric (optimizing LCP when FCP is bottleneck)
+
+## Performance Checklist
+
+After changes:
+- [ ] Measure impact (before/after)
+- [ ] Bundle size acceptable
+- [ ] Core Web Vitals within targets
+- [ ] No regressions in Lighthouse
+- [ ] Images optimized
+- [ ] Cache strategy documented
+
+## Related Guidance
+
+- `/code-quality` — code patterns affect performance
+- `/logging-observability` — monitoring performance
+- `/testing` — performance regression tests