ai-playbook 1.0.0

package/roles/software-developer/frontend/code-quality/best-practices.md

@@ -0,0 +1,309 @@
+# Code Quality: Best Practices
+
+High-quality code is readable, maintainable, and predictable. This guide covers naming, structure, and practices that make code a pleasure to work with.
+
+## Naming Conventions
+
+Clear names are worth the extra characters. Use established conventions for consistency.
+
+```javascript
+// Components: PascalCase
+function UserProfile() { }
+function ShoppingCart() { }
+function FormInput() { }
+
+// Functions and variables: camelCase
+function calculateTotal() { }
+let userCount = 0;
+const handleClick = () => { };
+
+// Constants: UPPER_SNAKE_CASE
+const MAX_RETRIES = 3;
+const API_BASE_URL = 'https://api.example.com';
+const DEFAULT_TIMEOUT = 5000;
+
+// Boolean variables: is/has/should prefix
+const isLoading = true;
+const hasError = false;
+const shouldRender = true;
+const isEnabled = true;
+
+// BAD: Unclear names
+let x = 10;        // What is x?
+let temp = [];     // Temporary what?
+let data = null;   // What data?
+let d = new Date(); // 'd' doesn't convey meaning
+
+// GOOD: Clear, specific names
+let maxConnectionRetries = 10;
+let temporaryUploadQueue = [];
+let cachedUserData = null;
+let requestStartTime = new Date();
+```
+
+## Function Size
+
+Keep functions small and focused. A function that fits on one screen is easier to understand.
+
+```javascript
+// BAD: 50-line function mixing concerns
+function processUserData(userId) {
+  // Validation
+  if (!userId) throw new Error('User ID required');
+  if (typeof userId !== 'number') throw new Error('Must be number');
+  
+  // Fetch data
+  const user = fetchUser(userId);
+  if (!user) throw new Error('User not found');
+  
+  // Transform data
+  const formatted = {
+    id: user.id,
+    displayName: `${user.firstName} ${user.lastName}`,
+    emails: user.emails.map(e => e.address),
+    createdAt: new Date(user.createdAt),
+    isActive: user.status === 'active'
+  };
+  
+  // Update cache
+  cache.set(`user:${userId}`, formatted);
+  
+  // Log
+  console.log(`Processed user ${userId}`);
+  
+  return formatted;
+}
+
+// GOOD: Small, focused functions
+function validateUserId(userId) {
+  if (!userId) throw new Error('User ID required');
+  if (typeof userId !== 'number') throw new Error('Must be number');
+}
+
+function formatUserData(user) {
+  return {
+    id: user.id,
+    displayName: `${user.firstName} ${user.lastName}`,
+    emails: user.emails.map(e => e.address),
+    createdAt: new Date(user.createdAt),
+    isActive: user.status === 'active'
+  };
+}
+
+function processUserData(userId) {
+  validateUserId(userId);
+  const user = fetchUser(userId);
+  const formatted = formatUserData(user);
+  cache.set(`user:${userId}`, formatted);
+  return formatted;
+}
+```
+
+## Avoid Deep Nesting
+
+Nesting makes code hard to follow. Keep it shallow using early returns, guard clauses, and extraction.
+
+```javascript
+// BAD: Deeply nested (hard to follow)
+function handleUserUpdate(user) {
+  if (user) {
+    if (user.isActive) {
+      if (user.email) {
+        if (user.profile) {
+          if (user.profile.updated) {
+            sendNotification(user.email, 'Profile updated');
+          }
+        }
+      }
+    }
+  }
+}
+
+// GOOD: Flat with guard clauses (clear flow)
+function handleUserUpdate(user) {
+  if (!user) return;
+  if (!user.isActive) return;
+  if (!user.email) return;
+  if (!user.profile?.updated) return;
+  
+  sendNotification(user.email, 'Profile updated');
+}
+
+// GOOD: Extract conditions
+function isValidUserForNotification(user) {
+  return user?.isActive && user?.email && user?.profile?.updated;
+}
+
+function handleUserUpdate(user) {
+  if (!isValidUserForNotification(user)) return;
+  sendNotification(user.email, 'Profile updated');
+}
+```
+
+## TypeScript for Type Safety
+
+Use TypeScript to catch errors at development time, not production.
+
+```javascript
+// WITHOUT TypeScript: bug found after deployment
+function getUser(id) {
+  return fetch(`/api/users/${id}`).then(r => r.json());
+}
+
+const user = getUser('invalid'); // Oops, id should be number
+user.toUpperCase(); // Oops, user is an object, not a string
+
+// WITH TypeScript: caught immediately
+function getUser(id: number): Promise<User> {
+  return fetch(`/api/users/${id}`).then(r => r.json());
+}
+
+const user = getUser('invalid'); // Error: Argument of type 'string' is not assignable to parameter of type 'number'
+user.toUpperCase(); // Error: Property 'toUpperCase' does not exist on type 'User'
+
+interface User {
+  id: number;
+  name: string;
+  email: string;
+}
+
+// Strong typing catches errors early
+function formatUserEmail(user: User): string {
+  return `${user.name} <${user.email}>`;
+}
+```
+
+## Import Organization
+
+Organize imports consistently: standard library → third-party → local.
+
+```javascript
+// GOOD: Organized imports
+import { useState, useEffect } from 'react';
+import { format } from 'date-fns';
+import axios from 'axios';
+
+import { UserCard } from './UserCard';
+import { api } from '../services/api';
+import { COLORS } from '../constants';
+
+// Within local imports, group by type:
+// Components → hooks → utilities → constants
+```
+
+## Comments are Not Excuses
+
+Comments should explain **why**, not **what**. If you need to comment what code does, refactor to be clearer.
+
+```javascript
+// BAD: Unnecessary comments (what is obvious from code)
+function add(a, b) {
+  // Add a and b
+  return a + b; // return the sum
+}
+
+const users = []; // Empty array for users
+
+// GOOD: Only necessary comments (why, not what)
+// Cache is cleared after 5 minutes to prevent stale data
+const CACHE_TTL = 5 * 60 * 1000;
+
+// We use a Set instead of array for O(1) lookup performance
+const seenIds = new Set();
+
+// Retry logic: exponential backoff with jitter to avoid thundering herd
+function calculateBackoff(attempt) {
+  const exponential = Math.pow(2, attempt) * 1000;
+  const jitter = Math.random() * exponential * 0.1;
+  return exponential + jitter;
+}
+```
+
+## DRY (Don't Repeat Yourself)
+
+If you find identical logic in multiple places, extract it.
+
+```javascript
+// BAD: Repeated validation
+function validateEmail(email) {
+  if (!email) throw new Error('Email required');
+  if (!email.includes('@')) throw new Error('Invalid email');
+}
+
+function validateUsername(username) {
+  if (!username) throw new Error('Username required');
+  if (username.length < 3) throw new Error('Username too short');
+}
+
+// GOOD: Reusable validation
+function required(value, fieldName) {
+  if (!value) throw new Error(`${fieldName} required`);
+}
+
+function minLength(value, min, fieldName) {
+  if (value.length < min) throw new Error(`${fieldName} minimum ${min} characters`);
+}
+
+function validateEmail(email) {
+  required(email, 'Email');
+  if (!email.includes('@')) throw new Error('Invalid email');
+}
+
+function validateUsername(username) {
+  required(username, 'Username');
+  minLength(username, 3, 'Username');
+}
+```
+
+## Code Review Checklist
+
+When reviewing code (yours or others), check:
+
+```
+Clarity & Readability:
+- [ ] Variable and function names are clear
+- [ ] Functions are small and focused (< 30 lines)
+- [ ] Logic is easy to follow
+- [ ] Comments explain why, not what
+
+Correctness:
+- [ ] No obvious bugs (off-by-one, null checks, type mismatches)
+- [ ] Error handling is appropriate
+- [ ] Edge cases are considered
+- [ ] Logic matches requirements
+
+Type Safety:
+- [ ] TypeScript types are correct
+- [ ] No use of 'any' unless absolutely necessary
+- [ ] Prop types documented
+
+Testing:
+- [ ] Code is testable (not too tightly coupled)
+- [ ] Complex logic has tests
+- [ ] Edge cases are tested
+
+Performance:
+- [ ] No obvious inefficiencies
+- [ ] No unnecessary re-renders (if React)
+- [ ] No blocking operations
+```
+
+## Code Quality Best Practices Checklist
+
+- [ ] All names follow conventions (PascalCase, camelCase, UPPER_SNAKE_CASE)
+- [ ] Functions are small and focused
+- [ ] Nesting is shallow (max 2-3 levels)
+- [ ] TypeScript types are used throughout
+- [ ] Imports organized consistently
+- [ ] Comments explain why, not what
+- [ ] No repeated code (DRY principle)
+- [ ] Dead code removed
+- [ ] No console.log() statements in production code
+- [ ] Code passes linter without warnings
+
+## Related Guidance
+
+- `/components` — component structure and naming  
+- `/testing` — writing testable code  
+- `/tools-setup` — linters, formatters, and tooling  
+- `/debugging` — understanding code behavior

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

@@ -0,0 +1,65 @@
+# Components
+
+Senior frontend developers design components that are reusable, maintainable, and composable.
+
+## Key Principles
+
+- **Single Responsibility** — component does one thing well
+- **Composability** — can be combined with other components
+- **Prop Clarity** — props are clear, typed, documented
+- **No Side Effects** — no surprise mutations or external effects
+- **Testability** — component behavior predictable and testable
+
+## Component Design Patterns
+
+### Container vs Presentational (Smart vs Dumb)
+- **Presentational** — receives data via props, renders UI, no state logic
+- **Container** — manages state, data fetching, passes to presentational
+- Use both for separation of concerns
+
+### Composition Over Inheritance
+- Build complex components from simpler ones
+- Avoids deep inheritance hierarchies
+- Easier to test and reason about
+
+### Render Props & Higher-Order Components
+- Extract reusable logic into shared patterns
+- Render props: pass function as prop for flexibility
+- HOCs: wrap component to add behavior
+- Hooks: modern alternative, preferred for new code
+
+## Props Design
+
+### What to Pass
+- Stable data (primitives, objects)
+- Callbacks for user actions
+- Render functions for flexibility
+- Configuration options
+
+### What NOT to Pass
+- Avoid prop drilling (passing through intermediate components)
+- Don't pass component instance state
+- Don't pass circular references
+
+Use context or state management for deeply nested data.
+
+## Component Lifecycle Concerns
+
+- **Mount** — initialize resources, fetch data
+- **Update** — respond to prop changes
+- **Unmount** — cleanup resources, cancel requests
+- Handle all three phases explicitly
+
+## Anti-Patterns
+
+- Monolithic components (>200 lines suggest decomposition)
+- Components that manage unrelated state
+- Mixing presentation and business logic
+- Props drilling through 3+ levels
+- Implicit dependencies (magic strings, hardcoded values)
+
+## Related Guidance
+
+- `../testing/` - testing component behavior
+- `../state-management/` - managing component data
+- `../code-quality/` - formatting and style standards

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

@@ -0,0 +1,273 @@
+# Components: Best Practices
+
+Senior frontend developers design components that balance reusability, maintainability, and clarity. This guide provides actionable patterns for building better components.
+
+## Design for Reusability
+
+Build components that solve a specific problem once, then reuse them everywhere. This requires thinking about what makes a component truly reusable.
+
+**Single Responsibility Principle (SRP):** Each component should have one reason to change. If you find yourself describing a component with "and," it probably does too much.
+
+```javascript
+// BAD: UserProfile does authentication, display, and data fetching
+function UserProfile({ userId }) {
+  const [user, setUser] = useState(null);
+  useEffect(() => {
+    fetchUser(userId).then(setUser);
+  }, [userId]);
+  
+  if (!user) return <div>Loading...</div>;
+  return (
+    <div>
+      <h2>{user.name}</h2>
+      <p>{user.email}</p>
+      <button onClick={() => logout()}>Logout</button>
+    </div>
+  );
+}
+
+// GOOD: Separate concerns
+function UserProfile({ user, onLogout }) {
+  return (
+    <div>
+      <h2>{user.name}</h2>
+      <p>{user.email}</p>
+      <button onClick={onLogout}>Logout</button>
+    </div>
+  );
+}
+
+function UserProfileContainer({ userId }) {
+  const [user, setUser] = useState(null);
+  
+  useEffect(() => {
+    fetchUser(userId).then(setUser);
+  }, [userId]);
+  
+  if (!user) return <div>Loading...</div>;
+  return <UserProfile user={user} onLogout={logout} />;
+}
+```
+
+**Composition over inheritance:** Build complex components by combining simpler ones rather than through inheritance.
+
+```javascript
+// GOOD: Compose smaller components
+function Card({ children, title, actions }) {
+  return (
+    <div className="card">
+      <div className="card-header">
+        <h3>{title}</h3>
+        <div className="card-actions">{actions}</div>
+      </div>
+      <div className="card-body">{children}</div>
+    </div>
+  );
+}
+
+function UserCard({ user, onEdit, onDelete }) {
+  return (
+    <Card
+      title={user.name}
+      actions={
+        <>
+          <button onClick={onEdit}>Edit</button>
+          <button onClick={onDelete}>Delete</button>
+        </>
+      }
+    >
+      <p>{user.email}</p>
+      <p>{user.role}</p>
+    </Card>
+  );
+}
+```
+
+## Props Design
+
+Well-designed props make components predictable and reusable. Props should communicate intent clearly.
+
+**Be explicit:** Each prop should have a clear name and purpose. Use TypeScript or JSDoc to document.
+
+```javascript
+// GOOD: Explicit props with documentation
+/**
+ * Button component
+ * @param {string} variant - 'primary' | 'secondary' | 'danger'
+ * @param {boolean} disabled - whether button is clickable
+ * @param {function} onClick - callback when clicked
+ * @param {ReactNode} children - button label
+ */
+function Button({ variant = 'primary', disabled = false, onClick, children }) {
+  return (
+    <button 
+      className={`btn btn-${variant}`}
+      disabled={disabled}
+      onClick={onClick}
+    >
+      {children}
+    </button>
+  );
+}
+```
+
+**Avoid prop drilling:** Don't pass props through multiple intermediate components to reach a deeply nested component. Use Context or state management instead.
+
+```javascript
+// BAD: Prop drilling through multiple levels
+function Page({ user }) {
+  return <MainLayout user={user} />;
+}
+
+function MainLayout({ user }) {
+  return <Sidebar user={user} />;
+}
+
+function Sidebar({ user }) {
+  return <UserMenu user={user} />;
+}
+
+function UserMenu({ user }) {
+  return <span>{user.name}</span>;
+}
+
+// GOOD: Use Context for deeply nested data
+const UserContext = createContext();
+
+function Page({ user }) {
+  return (
+    <UserContext.Provider value={user}>
+      <MainLayout />
+    </UserContext.Provider>
+  );
+}
+
+function UserMenu() {
+  const user = useContext(UserContext);
+  return <span>{user.name}</span>;
+}
+```
+
+## Component Lifecycle
+
+Components go through distinct phases. Handle each one explicitly.
+
+- **Mount:** Initialize resources, fetch data if needed
+- **Update:** Respond to prop or state changes
+- **Unmount:** Clean up resources, cancel pending requests
+
+```javascript
+function UserData({ userId }) {
+  const [data, setData] = useState(null);
+  const [error, setError] = useState(null);
+  
+  useEffect(() => {
+    let mounted = true;
+    
+    // Mount: fetch data
+    fetchUser(userId)
+      .then(result => {
+        if (mounted) setData(result);
+      })
+      .catch(err => {
+        if (mounted) setError(err);
+      });
+    
+    // Unmount: cleanup
+    return () => {
+      mounted = false; // prevent state updates after unmount
+    };
+  }, [userId]); // Update: refetch when userId changes
+  
+  if (error) return <div>Error: {error.message}</div>;
+  if (!data) return <div>Loading...</div>;
+  return <div>{data.name}</div>;
+}
+```
+
+## Performance Basics
+
+Use memoization strategically to prevent unnecessary re-renders, but don't optimize prematurely.
+
+```javascript
+// Memoize when:
+// 1. Component has complex render logic
+// 2. Receives expensive props (objects/functions from parent)
+// 3. Parent re-renders frequently
+
+const UserProfile = React.memo(function UserProfile({ user, onUpdate }) {
+  return (
+    <div>
+      <h2>{user.name}</h2>
+      <button onClick={onUpdate}>Update</button>
+    </div>
+  );
+});
+
+// For callbacks, use useCallback to maintain referential equality
+function Parent() {
+  const [count, setCount] = useState(0);
+  
+  const handleUpdate = useCallback(() => {
+    // update logic
+  }, []); // Dependencies matter!
+  
+  return <UserProfile user={user} onUpdate={handleUpdate} />;
+}
+```
+
+## Testing Approach
+
+Design components to be testable by keeping them simple and pure.
+
+```javascript
+// GOOD: Testable component
+function Button({ variant, disabled, onClick, children }) {
+  return (
+    <button className={`btn btn-${variant}`} disabled={disabled} onClick={onClick}>
+      {children}
+    </button>
+  );
+}
+
+// Easy to test: just check props map to output
+test('Button renders with correct variant', () => {
+  render(<Button variant="primary">Click me</Button>);
+  expect(screen.getByRole('button')).toHaveClass('btn-primary');
+});
+```
+
+## Documentation
+
+Code comments should explain **why**, not **what**. The code shows what it does; comments explain design decisions.
+
+```javascript
+// GOOD: Comments explain intent
+// We use a separate loading state instead of checking data === null
+// because null is also a valid data value (empty results)
+const [data, setData] = useState(null);
+const [isLoading, setIsLoading] = useState(false);
+
+// BAD: Obvious from code
+const [data, setData] = useState(null); // set data to null
+```
+
+## Component Best Practices Checklist
+
+- [ ] Component has single, clear responsibility
+- [ ] Props are explicit and typed
+- [ ] No prop drilling beyond 2 levels
+- [ ] Component handles mount, update, and unmount phases
+- [ ] Memoization used only where measurably beneficial
+- [ ] Rendering logic is pure (no side effects)
+- [ ] Component can be tested in isolation
+- [ ] Documentation explains design decisions, not code
+- [ ] Component reusable without modification
+- [ ] Dependent cleanup happens in unmount phase
+
+## Related Guidance
+
+- `/testing` — testing component behavior  
+- `/state-management` — managing component data  
+- `/code-quality` — naming and style standards  
+- `/performance` — optimization techniques