start-vibing 2.0.3 → 2.0.4

package/template/.claude/skills/debugging-patterns/SKILL.md

@@ -0,0 +1,484 @@
+---
+name: debugging-patterns
+description: Debugging strategies and error resolution patterns. Stack trace analysis, runtime errors, build errors, network issues. Use when debugging any type of error.
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+# Debugging Patterns - Error Resolution Best Practices
+
+## Purpose
+
+Expert guidance for debugging:
+
+- **Error Analysis** - Stack traces, error messages
+- **Runtime Issues** - Type errors, null references
+- **Build Errors** - Compilation, bundling
+- **Network Issues** - API, CORS, HTTP errors
+- **Performance Bugs** - Slow operations, memory leaks
+
+---
+
+## Debug Process
+
+```
+1. UNDERSTAND - What should happen vs what happens
+   ↓
+2. REPRODUCE - Consistent steps to trigger bug
+   ↓
+3. ISOLATE - Narrow down to specific code
+   ↓
+4. IDENTIFY - Find root cause
+   ↓
+5. FIX - Implement solution
+   ↓
+6. VERIFY - Confirm fix works + no regressions
+```
+
+---
+
+## Stack Trace Analysis
+
+### Reading Error Stack
+
+```
+TypeError: Cannot read properties of undefined (reading 'name')
+    at getUserName (src/utils/user.ts:45:23)
+    at ProfileCard (src/components/ProfileCard.tsx:12:18)
+    at renderWithHooks (node_modules/react-dom/...)
+```
+
+**Key Information:**
+- **Error Type**: `TypeError`
+- **Message**: `Cannot read properties of undefined`
+- **Property**: `name`
+- **Location**: `src/utils/user.ts:45:23` (file:line:column)
+- **Call Stack**: Shows how we got here
+
+### Fix Pattern
+
+```typescript
+// Error at line 45
+function getUserName(user: User) {
+  return user.name; // ERROR: user is undefined
+}
+
+// Fix: Add null check
+function getUserName(user: User | undefined): string {
+  return user?.name ?? 'Unknown';
+}
+
+// Or use assertion with clear error
+function getUserName(user: User | undefined): string {
+  if (!user) {
+    throw new Error('User is required for getUserName');
+  }
+  return user.name;
+}
+```
+
+---
+
+## Common Error Patterns
+
+### TypeError: Cannot read properties of undefined
+
+```typescript
+// Pattern: Accessing property on undefined
+const name = user.profile.name;
+
+// Fix 1: Optional chaining
+const name = user?.profile?.name ?? 'Unknown';
+
+// Fix 2: Early return
+if (!user?.profile) return null;
+const name = user.profile.name;
+
+// Fix 3: Default value
+const profile = user?.profile ?? { name: 'Unknown' };
+```
+
+### TypeError: X is not a function
+
+```typescript
+// Pattern: Calling non-function
+onClick(); // onClick is undefined
+
+// Fix 1: Check before calling
+onClick?.();
+
+// Fix 2: Provide default
+const handleClick = onClick ?? (() => {});
+handleClick();
+```
+
+### ReferenceError: X is not defined
+
+```typescript
+// Pattern: Using undefined variable
+console.log(userData); // userData not imported/declared
+
+// Fix: Import or declare
+import { userData } from './data';
+// or
+const userData = await fetchUserData();
+```
+
+### SyntaxError: Unexpected token
+
+```typescript
+// Pattern: Invalid JSON
+const data = JSON.parse(response);
+// SyntaxError: Unexpected token '<'
+
+// Fix: Check response before parsing
+if (!response.ok) {
+  throw new Error(`HTTP ${response.status}`);
+}
+const text = await response.text();
+try {
+  return JSON.parse(text);
+} catch {
+  throw new Error(`Invalid JSON: ${text.slice(0, 100)}`);
+}
+```
+
+---
+
+## TypeScript Errors
+
+### TS2339: Property does not exist
+
+```typescript
+// Error
+const env = process.env.NODE_ENV;
+// Property 'NODE_ENV' does not exist on type 'ProcessEnv'
+
+// Fix: Use bracket notation
+const env = process.env['NODE_ENV'];
+```
+
+### TS2532: Object is possibly undefined
+
+```typescript
+// Error
+const items = array.map(x => x.value);
+// Object is possibly 'undefined'
+
+// Fix 1: Non-null assertion (if certain)
+const items = array!.map(x => x.value);
+
+// Fix 2: Default value
+const items = (array ?? []).map(x => x.value);
+
+// Fix 3: Conditional
+const items = array ? array.map(x => x.value) : [];
+```
+
+### TS2345: Argument type mismatch
+
+```typescript
+// Error
+function greet(name: string) { }
+greet(user.name); // Argument of type 'string | undefined'
+
+// Fix 1: Provide default
+greet(user.name ?? 'Guest');
+
+// Fix 2: Assert
+greet(user.name!);
+
+// Fix 3: Guard
+if (user.name) greet(user.name);
+```
+
+### TS7053: Index signature
+
+```typescript
+// Error
+const value = obj[key];
+// Element implicitly has 'any' type
+
+// Fix: Type the index
+const value = (obj as Record<string, unknown>)[key];
+
+// Or define proper type
+interface MyObj {
+  [key: string]: string | undefined;
+}
+```
+
+---
+
+## Build Errors
+
+### Module Not Found
+
+```bash
+# Error
+Cannot find module './utils' or its corresponding type declarations
+
+# Check 1: File exists?
+ls src/utils.ts
+
+# Check 2: Extension needed?
+import { helper } from './utils.js';  # ESM requires extension
+
+# Check 3: Path alias configured?
+# Check tsconfig.json paths
+```
+
+### Duplicate Identifier
+
+```bash
+# Error
+Duplicate identifier 'User'
+
+# Fix: Check imports for conflicts
+# May have both named and default import
+import User from './User';
+import { User } from './types';  # Conflict!
+
+# Solution: Rename one
+import { User as UserType } from './types';
+```
+
+### ESM/CJS Compatibility
+
+```typescript
+// Error: require is not defined in ES module
+const fs = require('fs');
+
+// Fix: Use ESM import
+import fs from 'fs';
+import { readFileSync } from 'fs';
+
+// If must use require in ESM
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+```
+
+---
+
+## Network & API Errors
+
+### CORS Errors
+
+```
+Access to fetch at 'https://api.example.com' has been blocked by CORS policy
+```
+
+```typescript
+// Server-side fix (add headers)
+res.setHeader('Access-Control-Allow-Origin', 'https://yoursite.com');
+res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
+
+// Client-side workaround (proxy in dev)
+// vite.config.ts
+export default {
+  server: {
+    proxy: {
+      '/api': {
+        target: 'https://api.example.com',
+        changeOrigin: true,
+      },
+    },
+  },
+};
+```
+
+### HTTP Error Handling
+
+```typescript
+async function fetchWithErrorHandling<T>(url: string): Promise<T> {
+  const response = await fetch(url);
+
+  if (!response.ok) {
+    // Get error details
+    let message: string;
+    try {
+      const error = await response.json();
+      message = error.message || response.statusText;
+    } catch {
+      message = response.statusText;
+    }
+
+    throw new Error(`${response.status} ${message}`);
+  }
+
+  return response.json();
+}
+```
+
+### Network Timeout
+
+```typescript
+async function fetchWithTimeout(url: string, timeout = 5000) {
+  const controller = new AbortController();
+  const id = setTimeout(() => controller.abort(), timeout);
+
+  try {
+    const response = await fetch(url, { signal: controller.signal });
+    clearTimeout(id);
+    return response;
+  } catch (error) {
+    clearTimeout(id);
+    if (error instanceof Error && error.name === 'AbortError') {
+      throw new Error(`Request timeout after ${timeout}ms`);
+    }
+    throw error;
+  }
+}
+```
+
+---
+
+## React Debugging
+
+### "Cannot update a component while rendering"
+
+```typescript
+// Error: State update during render
+function Component({ value }) {
+  const [state, setState] = useState(0);
+  setState(value); // ERROR!
+
+  // Fix: Use useEffect
+  useEffect(() => {
+    setState(value);
+  }, [value]);
+}
+```
+
+### "Too many re-renders"
+
+```typescript
+// Error: Infinite loop
+function Component() {
+  const [count, setCount] = useState(0);
+  setCount(count + 1); // Causes re-render, which sets count...
+
+  // Fix: Add condition or use effect
+  useEffect(() => {
+    if (count < 10) {
+      setCount(c => c + 1);
+    }
+  }, [count]);
+}
+```
+
+### "Invalid hook call"
+
+```typescript
+// Error: Hook outside component or conditional
+function Component() {
+  if (condition) {
+    const [state] = useState(0); // ERROR!
+  }
+}
+
+// Fix: Hooks must be at top level
+function Component() {
+  const [state] = useState(0); // OK
+  if (condition) {
+    // use state here
+  }
+}
+```
+
+---
+
+## Debug Commands
+
+### Git - Find Breaking Commit
+
+```bash
+# Start bisect
+git bisect start
+git bisect bad HEAD
+git bisect good abc123  # Last known good commit
+
+# Test and mark each commit
+git bisect good  # or bad
+
+# End bisect
+git bisect reset
+```
+
+### Find Error in Code
+
+```bash
+# Search for error message
+grep -rn "specific error text" src/
+
+# Search for pattern
+grep -rn "throw new Error" src/ --include="*.ts"
+
+# Find file with symbol
+grep -rn "functionName" src/ --include="*.ts" -l
+```
+
+### Bun Debugging
+
+```bash
+# Debug mode
+bun --inspect src/index.ts
+
+# With breakpoint on start
+bun --inspect-brk src/index.ts
+
+# Low memory mode (for memory issues)
+bun --smol src/index.ts
+```
+
+---
+
+## Debugging Checklist
+
+### Before You Start
+
+- [ ] Can you reproduce the bug?
+- [ ] Do you have the exact error message?
+- [ ] What changed recently? (`git log`, `git diff`)
+
+### Investigation
+
+- [ ] Read the full error message and stack trace
+- [ ] Check the line number mentioned in error
+- [ ] Add console.log at key points
+- [ ] Check network tab for API errors
+
+### After Fix
+
+- [ ] Does the fix work for all cases?
+- [ ] Did you add tests to prevent regression?
+- [ ] Did you handle edge cases?
+
+---
+
+## Agent Integration
+
+This skill is used by:
+
+- **debugger** agent
+- **error-stack-analyzer** agent
+- **type-error-resolver** agent
+- **runtime-error-fixer** agent
+- **network-debugger** agent
+- **build-error-fixer** agent
+
+---
+
+## FORBIDDEN
+
+1. **Swallowing errors silently** - Always log or handle
+2. **Using `any` to hide errors** - Fix the actual type issue
+3. **`@ts-ignore` without comment** - Use `@ts-expect-error` with explanation
+4. **Empty catch blocks** - At minimum, log the error
+5. **Fixing symptoms not causes** - Find and fix root cause
+
+---
+
+## Version
+
+- **v1.0.0** - Initial implementation based on 2024-2025 debugging patterns