ai-playbook 1.0.0

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

@@ -0,0 +1,149 @@
+# Debugging
+
+Senior frontend developers debug systematically. Don't guess — observe, hypothesize, test.
+
+## Debugging Process
+
+1. **Reproduce** — isolate when bug occurs
+2. **Observe** — what's different from expected?
+3. **Hypothesis** — what could cause this?
+4. **Test** — verify hypothesis
+5. **Fix** — make minimal change
+6. **Verify** — bug gone, no regressions
+
+Rushing skips steps, wastes time.
+
+## Browser DevTools
+
+### Console
+- View errors/warnings
+- Log data with `console.log()`
+- Use `console.table()` for structured data
+- Group logs with `console.group()`
+- Measure with `console.time()`
+
+### Sources/Debugger
+- Set breakpoints (click line number)
+- Step through code (step over/in/out)
+- Inspect variable values
+- Conditional breakpoints
+- Watch expressions
+
+### Elements/Inspector
+- Inspect DOM structure
+- Change CSS temporarily
+- View computed styles
+- Check classes/attributes
+- Debug layout issues
+
+### Network Tab
+- View API requests/responses
+- Check status codes
+- View response data
+- Monitor timing
+- Throttle network (slow 3G simulation)
+
+### Performance Tab
+- Record and analyze runtime performance
+- Identify slow operations
+- Check for jank
+- Analyze flame charts
+
+### React DevTools
+- Inspect component tree
+- View props and state
+- Track re-renders
+- Highlight updates
+- Profile performance
+
+## Common Bugs & Solutions
+
+### Component Not Rendering
+- Check console for errors
+- Verify JSX syntax (components PascalCase)
+- Check props passed correctly
+- Verify conditional render logic
+- Check CSS display/visibility
+
+### State Not Updating
+- Mutating state directly (use setState)
+- Not triggering re-render (wrong hook)
+- Race conditions (async state)
+- Stale closure (old props in handler)
+- Not returning new object (mutations)
+
+### API Calls Not Firing
+- Check Network tab for request
+- Verify endpoint URL
+- Check request headers/body
+- Verify loading/error handling
+- Check CORS settings
+- Verify API key/auth
+
+### Memory Leaks
+- Event listeners not removed
+- Timers (setTimeout, setInterval) not cleared
+- Subscriptions not unsubscribed
+- Stale component references
+- Circular references
+
+### Performance Issues
+- Check DevTools Performance tab
+- Identify slow operations
+- Unnecessary re-renders
+- Large bundle size
+- Slow network requests
+
+## Debugging Techniques
+
+### Strategic Logging
+- Log at decision points
+- Log data structures with context
+- Use descriptive log messages
+- Remove logs before commit (or use debug flag)
+
+### Rubber Duck Debugging
+- Explain code to someone (or rubber duck)
+- Explaining forces clarity
+- Often find bug while explaining
+
+### Narrowing Scope
+- Comment out code to isolate issue
+- Temporarily remove features
+- Use git bisect to find bad commit
+- Create minimal reproduction case
+
+### Reproducing Bugs
+- Get exact steps to reproduce
+- Isolate inputs that trigger bug
+- Create minimal test case
+- Debug in controlled environment
+
+## Debugging Checklist
+
+When bug occurs:
+- [ ] Console errors/warnings checked
+- [ ] Reproduction steps documented
+- [ ] Hypothesis written down
+- [ ] DevTools used (console, debugger, network)
+- [ ] Data at each step verified
+- [ ] Code changes minimal
+- [ ] Tests added for bug
+- [ ] No new issues introduced
+
+## Anti-Patterns
+
+- Guessing instead of investigating
+- Adding lots of `console.log()` without removing
+- Not using debugger (just relying on logs)
+- Ignoring error messages
+- Changing multiple things at once
+- Not reproducing bug reliably
+- Band-aid fixes without fixing root cause
+- Not testing fix thoroughly
+
+## Related Guidance
+
+- `/logging-observability` — logging for debugging
+- `/testing` — preventing bugs with tests
+- `/code-quality` — clean code is easier to debug

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

@@ -0,0 +1,329 @@
+# Debugging: Best Practices
+
+Debugging is a systematic skill. The faster you find bugs, the more productive you are. This guide covers proven techniques for tracking down problems efficiently.
+
+## Reproduction is Half the Battle
+
+The hardest part of debugging is reproducing the problem consistently. Once you can reliably reproduce it, the fix is often obvious.
+
+```javascript
+// GOOD: Document reproduction steps clearly
+/*
+Bug: User avatar not loading on profile page
+
+Steps to reproduce:
+1. Log in as user
+2. Navigate to profile page
+3. Avatar does not appear (broken image icon shown)
+4. Network tab shows 404 for avatar URL
+
+Expected: Profile picture loads from /avatars/{userId}.jpg
+Actual: Returns 404
+
+Environment: Chrome 120, macOS Sonoma
+Last worked: Version 2.1.0
+First noticed: Version 2.3.1
+*/
+
+// During debugging, keep detailed notes:
+// What works vs doesn't work
+// What changed between working and broken
+// Any error messages (exact text matters!)
+// Browser/device/OS combination
+// Network conditions if relevant
+```
+
+## Use DevTools Effectively
+
+Browser DevTools are powerful when used correctly.
+
+```javascript
+// Debugging React components:
+// 1. Install React DevTools extension
+// 2. Open DevTools → Components tab
+// 3. Inspect component tree, view current props/state
+// 4. Simulate prop changes to test behavior
+// 5. Check if component re-renders when expected
+
+// Common DevTools tricks:
+
+// View element styles and specificity
+// Inspect → Styles tab
+// Hover over CSS rules to see which file they come from
+
+// Watch variables change in real-time
+// Inspect → Console
+function debugValue(name, value) {
+  console.log(`${name}:`, value);
+  window[`debug_${name}`] = value; // Access in console as window.debug_value
+}
+
+// Network debugging:
+// Network tab → filter by type
+// Check response headers (Content-Type, Cache-Control)
+// Check request headers (Authorization, User-Agent)
+// Watch for failed requests (red) vs slow requests (yellow)
+
+// Performance profiling:
+// Performance tab → record
+// Perform action
+// Analyze flame chart to find slow operations
+```
+
+## Isolate the Problem
+
+Narrow down where the bug is by removing variables.
+
+```javascript
+// BAD: Vague debugging
+// Component not working, let me add console.log everywhere
+
+// GOOD: Systematic isolation
+function UserProfile({ userId }) {
+  const [user, setUser] = useState(null);
+  
+  useEffect(() => {
+    // Is the API called?
+    console.log('Fetching user:', userId);
+    
+    fetchUser(userId)
+      .then(data => {
+        // Does API return data?
+        console.log('API returned:', data);
+        setUser(data);
+      })
+      .catch(err => {
+        // Does API fail?
+        console.error('API error:', err);
+      });
+  }, [userId]);
+  
+  // Is state set correctly?
+  console.log('Current state:', user);
+  
+  if (!user) return <div>Loading...</div>;
+  
+  return <div>{user.name}</div>;
+}
+
+// Isolate steps:
+// 1. Does API get called with correct userId?
+// 2. Does API return expected data?
+// 3. Is state set correctly after API returns?
+// 4. Does component render using that state?
+
+// Once you find which step fails, focus there
+```
+
+## React-Specific Debugging
+
+React has specific patterns and tools for debugging.
+
+```javascript
+// Common React bugs:
+
+// 1. Stale closure in useEffect
+// BAD: useEffect uses value that might be stale
+function Timer() {
+  const [count, setCount] = useState(0);
+  
+  useEffect(() => {
+    const interval = setInterval(() => {
+      setCount(count + 1); // Always increments by 1, even if count changed
+    }, 1000);
+    
+    return () => clearInterval(interval);
+  }, []); // Missing count dependency
+}
+
+// GOOD: Include count in dependencies
+useEffect(() => {
+  const interval = setInterval(() => {
+    setCount(count + 1);
+  }, 1000);
+  
+  return () => clearInterval(interval);
+}, [count]);
+
+// OR use functional setState
+useEffect(() => {
+  const interval = setInterval(() => {
+    setCount(c => c + 1); // Always has current value
+  }, 1000);
+  
+  return () => clearInterval(interval);
+}, []);
+
+// 2. Infinite loops from missing dependencies
+// Every render calls effect, effect triggers re-render
+useEffect(() => {
+  setData(someValue); // If someValue is from props/state, add to dependency array
+}, []); // Bug: someValue changes but effect doesn't re-run
+
+// 3. Memory leaks from uncleared timers/listeners
+// BAD: Listener added but never removed
+useEffect(() => {
+  window.addEventListener('resize', handleResize);
+  // No cleanup - listener accumulates
+}, []);
+
+// GOOD: Always cleanup
+useEffect(() => {
+  window.addEventListener('resize', handleResize);
+  return () => {
+    window.removeEventListener('resize', handleResize);
+  };
+}, []);
+
+// Use React DevTools Profiler:
+// 1. Open DevTools → Profiler tab
+// 2. Record interactions
+// 3. See which components rendered
+// 4. Identify unnecessary re-renders
+```
+
+## Network Debugging
+
+Many bugs are actually network issues.
+
+```javascript
+// Network tab shows:
+// - Failed requests (red = 4xx/5xx, gray = blocked)
+// - Slow requests (larger bars = slower)
+// - Response sizes (watch for large payloads)
+// - Caching (check Cache-Control headers)
+
+// Common network bugs:
+
+// 1. CORS errors
+// Error: Access to XMLHttpRequest blocked by CORS policy
+// Fix: Server must allow Origin in Access-Control-Allow-Origin
+
+// 2. Timeout issues
+// Request takes > 30s and browser cancels
+// Fix: Implement timeout handling, show loading state
+
+// 3. Authentication missing
+// 401 responses mean missing/expired token
+// Fix: Check authorization header, refresh token logic
+
+// 4. Wrong endpoint
+// 404 means URL doesn't exist
+// Fix: Check API documentation, verify URL construction
+
+function debugNetworkRequest(url) {
+  const start = performance.now();
+  
+  fetch(url)
+    .then(r => {
+      const duration = performance.now() - start;
+      console.log(`${url} - ${r.status} - ${duration}ms`);
+      return r.json();
+    })
+    .catch(err => {
+      const duration = performance.now() - start;
+      console.error(`${url} - Failed after ${duration}ms:`, err.message);
+    });
+}
+```
+
+## Rubber Duck Debugging
+
+Explaining your code to someone (or something) often reveals the bug.
+
+```javascript
+// Talk through your code step by step:
+// "This function takes userId"
+// "Fetches user from API"
+// "Sets user state"
+// "...wait, what if userId is undefined? We don't check that"
+// "Oh! When userId is null, fetch URL becomes /api/users/null"
+// "That's why we get 404"
+
+// You found the bug by explaining it
+
+// Benefits of rubber duck debugging:
+// - Forces you to think through logic carefully
+// - Slows you down (good for thinking)
+// - Works even with non-technical duck
+// - Free and always available
+```
+
+## Version Control Debugging
+
+Use git to find when bugs were introduced.
+
+```javascript
+// git bisect: binary search for the commit that broke things
+git bisect start
+git bisect bad   # Current version is broken
+git bisect good v1.0.0  # Last known good version
+
+// Git tests commits between good and bad
+// You test each one: works or broken
+// Eventually finds exact commit that introduced bug
+
+git bisect log   # See history of bisect
+git bisect reset # Return to original branch
+
+// Once you find the bad commit:
+git show <commit>  # See what changed
+git log -p <commit>~1..<commit>  # See the diff
+git blame path/to/file  # See who changed each line
+
+// Example workflow:
+// "Bug appeared in version 2.3.0"
+// "Last known good: 2.2.0"
+git bisect start
+git bisect bad v2.3.0
+git bisect good v2.2.0
+# Git checks out commit halfway between
+# Test: does bug exist?
+# Tell git: git bisect bad (or git bisect good)
+# Repeat until found exact commit
+```
+
+## Debugging Checklist
+
+```
+Before starting:
+- [ ] Reproduced the bug consistently
+- [ ] Read the error message carefully (exact text)
+- [ ] Checked browser console (DevTools)
+- [ ] Checked network tab (failed requests?)
+- [ ] Cleared cache/hard refresh
+
+During debugging:
+- [ ] Used console logging to track values
+- [ ] Used debugger breakpoints
+- [ ] Isolated the problem area
+- [ ] Checked assumptions
+- [ ] Verified dependencies (useEffect, imports)
+
+React-specific:
+- [ ] Checked React DevTools component tree
+- [ ] Verified state and props values
+- [ ] Checked for missing useEffect dependencies
+- [ ] Verified cleanup functions run
+- [ ] Checked for stale closures
+
+Network:
+- [ ] Verified request goes to correct URL
+- [ ] Verified response status (200, 404, 500?)
+- [ ] Checked response headers
+- [ ] Verified authentication header sent
+- [ ] Checked for CORS errors
+
+After finding bug:
+- [ ] Understand root cause
+- [ ] Write test to prevent regression
+- [ ] Check for similar bugs elsewhere
+- [ ] Update documentation if needed
+```
+
+## Related Guidance
+
+- `/testing` — writing tests to prevent bugs  
+- `/code-quality` — clean code is easier to debug  
+- `/logging-observability` — comprehensive logging helps debugging  
+- `/tools-setup` — debugging tools configuration

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

@@ -0,0 +1,19 @@
+# Frontend Examples
+
+This folder is reserved for larger frontend examples that complement the topic
+guides under `components/`, `state-management/`, `testing/`, and related folders.
+
+## Use Cases
+
+- Complete form implementation examples.
+- Component decomposition before-and-after examples.
+- Accessibility remediation walkthroughs.
+- Performance profiling and optimization narratives.
+
+## Related Files
+
+- `../components/`
+- `../state-management/`
+- `../testing/`
+- `../accessibility/`
+- `../performance/`

package/roles/software-developer/frontend/examples/checklists.md

@@ -0,0 +1,8 @@
+# Frontend Example Checklist
+
+- [ ] State the user workflow or UI behavior.
+- [ ] Include component structure and state ownership.
+- [ ] Cover loading, empty, error, and success states.
+- [ ] Include accessibility expectations.
+- [ ] Include tests that verify user-observable behavior.
+- [ ] Include performance or observability notes when relevant.

package/roles/software-developer/frontend/examples/examples.md

@@ -0,0 +1,17 @@
+# Frontend Example Template
+
+```markdown
+# Frontend Scenario
+
+## User Flow
+
+Describe the interaction from the user's perspective.
+
+## Component Shape
+
+List the main components and state ownership.
+
+## Verification
+
+List unit, integration, accessibility, and browser checks.
+```

package/roles/software-developer/frontend/logging-observability/README.md

@@ -0,0 +1,196 @@
+# Logging & Observability
+
+Senior frontend developers instrument code with proper logging and monitoring. What you can't measure, you can't improve.
+
+## Logging Principles
+
+- **Structured Logging** — machine-readable format (JSON)
+- **Log Levels** — debug, info, warn, error
+- **Context** — include relevant data with logs
+- **No Secrets** — never log API keys, tokens, passwords
+- **Cleanup** — remove debug logs before production
+
+## Log Levels
+
+### DEBUG
+- Development only
+- Detailed diagnostic information
+- Variable values, function calls
+- Remove before committing
+
+### INFO
+- General informational messages
+- User actions (login, form submit)
+- State changes
+- API calls
+
+### WARN
+- Unexpected but recoverable
+- Deprecated API usage
+- Performance concerns
+- Fallbacks being used
+
+### ERROR
+- Errors that impact functionality
+- Exceptions/crashes
+- Failed API calls
+- Missing resources
+
+## Structured Logging Example
+
+```javascript
+// Bad: unstructured
+console.log('User logged in')
+
+// Good: structured with context
+console.log({
+  level: 'INFO',
+  timestamp: new Date().toISOString(),
+  event: 'user_login',
+  userId: user.id,
+  email: user.email,
+  duration_ms: 234
+})
+```
+
+## Common Things to Log
+
+### User Actions
+- Login/logout
+- Form submissions
+- Navigation changes
+- Button clicks (important ones)
+- Modal open/close
+
+### Data Flow
+- API requests (URL, method, status)
+- API responses (status, response time)
+- Data fetches and updates
+- State changes
+- Cache hits/misses
+
+### Errors
+- Uncaught exceptions
+- API failures
+- Network errors
+- Validation failures
+- Timeouts
+
+### Performance
+- Page load time
+- API response times
+- Slow renders
+- Memory usage
+- Bundle size
+
+## What NOT to Log
+
+- Passwords, tokens, API keys
+- Personal information (SSN, credit cards)
+- Large objects (log relevant fields only)
+- Frequent noisy events (every keystroke)
+- Stack traces for expected errors
+
+## Logging Best Practices
+
+### Use Logging Library
+- winston
+- bunyan
+- pino
+- loglevel
+
+```javascript
+import { createLogger } from 'winston'
+
+const logger = createLogger({
+  format: 'json',
+  level: process.env.LOG_LEVEL || 'info'
+})
+
+logger.info('User action', { userId, action: 'login' })
+```
+
+### Log Early, Log Often
+- Log at function entry (especially for errors)
+- Log at decision points
+- Log state transitions
+- Log async operations start/end
+
+### Use Request IDs
+- Trace across multiple functions
+- Correlate frontend + backend logs
+- Helps in debugging distributed issues
+
+```javascript
+const requestId = generateId()
+logger.info('Request started', { requestId, endpoint: '/api/users' })
+// ... do stuff ...
+logger.info('Request completed', { requestId, status: 200 })
+```
+
+## Monitoring & Observability
+
+### Metrics to Track
+- **Errors** — error rates, crash rates
+- **Performance** — page load, API latency
+- **Usage** — active users, feature usage
+- **Business** — conversions, revenue
+
+### Tools
+- Google Analytics (usage)
+- Sentry (error tracking)
+- DataDog (APM/monitoring)
+- Rollbar (error monitoring)
+- Custom dashboards
+
+### Error Reporting
+- Catch unhandled errors
+- Send to error service
+- Include context (user, page, timestamp)
+- Don't send sensitive data
+
+```javascript
+window.addEventListener('error', (event) => {
+  logError({
+    message: event.message,
+    stack: event.error.stack,
+    url: window.location.href,
+    timestamp: new Date()
+  })
+})
+```
+
+### Real User Monitoring
+- Track real user experience
+- Monitor Core Web Vitals
+- Correlate with errors
+- Identify performance issues
+
+## Logging Anti-Patterns
+
+- Logging everything (noise)
+- Not logging failures
+- Logging without context
+- Logging sensitive data
+- Using console.log in production code
+- Inconsistent format
+- Logs too verbose or too sparse
+- Not rotating/cleaning logs
+
+## Logging Checklist
+
+Before pushing:
+- [ ] Debug logs removed
+- [ ] Info/warn/error logs meaningful
+- [ ] No sensitive data logged
+- [ ] Context included with logs
+- [ ] Errors properly caught and logged
+- [ ] Performance metrics logged
+- [ ] Log statements have appropriate levels
+- [ ] Monitoring tools configured
+
+## Related Guidance
+
+- `/debugging` — using logs to debug
+- `/testing` — testing logging behavior
+- `/code-quality` — consistent log formatting