@tinkcarlos/skillora 0.2.0

package/.claude/skills/fullstack-developer/references/bug-prevention.md

@@ -0,0 +1,914 @@
+# Bug Prevention & Detection Guide
+
+> Prevention is cheaper than debugging. This guide integrates patterns from bug-fixing and code-review skills.
+
+## 🔴 Universal Prevention Rules (All Languages/Frameworks)
+
+These six patterns cause bugs across **any** tech stack. Check them before every code submission.
+
+### 1. Batch Callback Processing
+
+**Problem**: Processing items one-by-one in event callbacks causes UI freeze or resource exhaustion.
+
+```
+❌ Bad:  on_item_received(item) → immediately update UI
+✅ Good: on_item_received(item) → add to buffer → timer flushes buffer every N ms
+```
+
+**Detection**: "If 1000 events arrive in 1 second, will the UI freeze?"
+
+### 2. Resource Release Completeness
+
+**Problem**: Timeout alone doesn't guarantee resource release.
+
+```
+❌ Bad:  resource.stop(); wait(2000);  // assume released
+✅ Good: resource.stop(); if (!wait(2000)) { force_terminate(); wait(); }
+```
+
+**Detection**: "If the operation times out, is the resource truly released?"
+
+### 3. Exception Granularity
+
+**Problem**: Outer try-catch aborts entire operation on single failure.
+
+```
+❌ Bad:  try { for item in items: process(item) } catch: pass  // entire loop aborts
+✅ Good: for item in items: try { process(item) } catch: continue  // only skip failed item
+```
+
+**Detection**: "If one iteration fails, will the entire loop abort?"
+
+### 4. Idempotent Creation
+
+**Problem**: Creating entities without existence check causes duplicates.
+
+```
+❌ Bad:  create_entity(name, data)
+✅ Good: existing = find_by_name(name); if existing: return existing; else: create_entity(unique_name, data)
+```
+
+**Detection**: "If this function is called twice with the same input, will it create duplicates?"
+
+### 5. Shared State in Concurrent Code
+
+**Problem**: Direct read/write of shared variables without synchronization.
+
+```
+❌ Bad:  self.cancelled = True  // in thread A, read in thread B
+✅ Good: with lock: self.cancelled = True  // or use atomic/thread-safe primitive
+```
+
+**Detection**: "If two threads read/write this variable, is there a race condition?"
+
+### 6. Cleanup on Close/Destroy
+
+**Problem**: Assuming child resources auto-cleanup when parent closes.
+
+```
+❌ Bad:  on_close() { /* nothing, assume GC handles it */ }
+✅ Good: on_close() { stop_timer(); cancel_thread(); close_connection(); }
+```
+
+**Detection**: "When the window/connection/process closes, are all child resources stopped?"
+
+---
+
+## Core Principles (From bug-fixing)
+
+1. **Never fix what you don't understand** — A fix without understanding is a landmine
+2. **Fix root cause, not symptoms** — Symptoms resurface elsewhere
+3. **Configuration over hardcode** — Avoid hardcoded lists, use dynamic detection
+4. **Hunt similar bugs** — After finding one bug, search entire project for same pattern
+5. **Full-scope investigation** — Code, DB, configs, migrations, environment files
+
+---
+
+## 🔥 Most Common Issues (80/20 Rule)
+
+| Issue | Frequency | Impact |
+|-------|-----------|--------|
+| **CORS errors** | Very High | Blocks all API calls |
+| **Field name mismatch** (camelCase/snake_case) | Very High | Data not displayed |
+| **Missing error handling** | High | Silent failures |
+| **useEffect cleanup missing** | High | Memory leaks |
+| **Input validation gaps** | High | Security + crashes |
+| **N+1 queries** | High | Performance |
+| **Auth token issues** | Medium | 401 errors |
+| **Type mismatch** (string vs number) | Medium | Runtime errors |
+| **Missing loading states** | Medium | Bad UX |
+| **Database migration missing** | Medium | Column not found |
+
+---
+
+## Hidden Bug Categories (Most Dangerous)
+
+| Category | Characteristics | Difficulty | Severity |
+|----------|----------------|------------|----------|
+| **Data Races** | Only occurs under concurrency | 🔴 Very Hard | 🔴 Critical |
+| **Memory Leaks** | Only exposed after long runtime | 🔴 Very Hard | 🟠 High |
+| **State Inconsistency** | Triggered by specific operation sequence | 🟠 Hard | 🔴 Critical |
+| **Timing Issues** | Depends on execution order | 🟠 Hard | 🟠 High |
+| **Resource Leaks** | Uncleared on exception paths | 🟡 Medium | 🟠 High |
+
+---
+
+## 1. Data Race Prevention
+
+### Shared State Modification (Most Dangerous)
+
+```python
+# 🔴 BUG: Modifying shared singleton state
+class ChatService:
+    def __init__(self):
+        self.agent = load_agent()  # Shared singleton
+    
+    async def chat(self, user_input, llm_id=None):
+        if llm_id:
+            self.agent.llm_provider_id = llm_id  # 💀 Affects ALL users!
+        await self.executor.run(self.agent, user_input)
+
+# ✅ CORRECT: Pass through parameters
+async def chat(self, user_input, llm_id=None):
+    await self.executor.run(
+        self.agent, user_input,
+        override_llm_id=llm_id  # Pass as parameter
+    )
+```
+
+### Detection Commands
+
+```bash
+# Python: State modification in async functions
+grep -rn "self\.[a-z_]* = " --include="*.py" | grep -v "__init__"
+
+# Module-level mutable objects (dangerous)
+grep -rn "^[a-z_]* = \[\]\|^[a-z_]* = {}" --include="*.py"
+```
+
+---
+
+## 2. Memory & Resource Leak Prevention
+
+### Frontend Event Listener Leak
+
+```typescript
+// 🔴 BUG: No cleanup
+useEffect(() => {
+    window.addEventListener('resize', handleResize);
+}, []);
+
+// ✅ CORRECT: Cleanup on unmount
+useEffect(() => {
+    window.addEventListener('resize', handleResize);
+    return () => window.removeEventListener('resize', handleResize);
+}, []);
+```
+
+### Backend Connection Leak
+
+```python
+# 🔴 BUG: Connection not closed on exception
+async def query():
+    conn = await pool.acquire()
+    result = await conn.fetch("SELECT ...")  # Exception here = leak
+    await pool.release(conn)
+
+# ✅ CORRECT: Context manager
+async def query():
+    async with pool.acquire() as conn:
+        return await conn.fetch("SELECT ...")
+```
+
+### Detection Commands
+
+```bash
+# useEffect without cleanup
+grep -rn "useEffect" --include="*.tsx" -A 8 | grep -B 6 "}, \[\])" | grep -v "return () =>"
+
+# Unclosed connections
+grep -rn "\.acquire()\|\.open(" --include="*.py" | grep -v "with\|async with"
+
+# setInterval without clear
+grep -rn "setInterval\|setTimeout" --include="*.ts" -A 5 | grep -v "clearInterval\|clearTimeout"
+```
+
+---
+
+## 3. State Inconsistency Prevention
+
+### Optimistic Update Without Rollback
+
+```typescript
+// 🔴 BUG: No proper rollback
+async function deleteItem(id) {
+    setItems(items.filter(i => i.id !== id));  // Optimistic
+    try {
+        await api.delete(id);
+    } catch (e) {
+        // 💀 Other operations may have modified items
+        setItems(backup);  // Stale backup
+    }
+}
+
+// ✅ CORRECT: Use functional update
+async function deleteItem(id) {
+    const previousItems = items;
+    setItems(prev => prev.filter(i => i.id !== id));
+    try {
+        await api.delete(id);
+    } catch (e) {
+        setItems(previousItems);
+        showError('Delete failed');
+    }
+}
+```
+
+### Cache & Database Inconsistency
+
+```python
+# 🔴 BUG: Delete cache first = stale data cached
+await cache.delete(f"user:{user_id}")
+await db.update(user_id, data)  # Read request may cache old data
+
+# ✅ CORRECT: Update DB first, then delete cache
+await db.update(user_id, data)
+await cache.delete(f"user:{user_id}")
+```
+
+---
+
+## 4. Timing & Concurrency Prevention
+
+### Missing Await
+
+```typescript
+// 🔴 BUG: Not awaited = race condition
+async function loadData() {
+    fetchUserProfile();  // 💀 Fire and forget
+    fetchUserOrders();
+}
+
+// ✅ CORRECT: Await or Promise.all
+async function loadData() {
+    const [profile, orders] = await Promise.all([
+        fetchUserProfile(),
+        fetchUserOrders()
+    ]);
+}
+```
+
+### Token Refresh Race
+
+```typescript
+// 🔴 BUG: Multiple refresh calls
+async function apiCall(url) {
+    if (isTokenExpired()) {
+        await refreshToken();  // 💀 Multiple calls = multiple refreshes
+    }
+    return fetch(url);
+}
+
+// ✅ CORRECT: Singleton refresh promise
+let refreshPromise = null;
+async function apiCall(url) {
+    if (isTokenExpired()) {
+        if (!refreshPromise) {
+            refreshPromise = refreshToken().finally(() => refreshPromise = null);
+        }
+        await refreshPromise;
+    }
+    return fetch(url);
+}
+```
+
+---
+
+## 5. Frontend-Backend-Database Sync Prevention
+
+### Contract Mismatch Detection
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| UI shows success, action failed | Not reading response status | Check response handling |
+| Data not updating | Wrong response field | Compare schemas |
+| Field undefined | Naming convention differs | camelCase vs snake_case |
+| **Column not found** | Missing migration | Create and run migration |
+| **Null constraint error** | Required field missing | Check nullable settings |
+| **Type conversion error** | DB type ≠ code type | Align types across layers |
+
+```bash
+# Compare validation rules
+grep -rn "maxLength\|max:" --include="*.ts"  # Frontend
+grep -rn "max_length\|MaxLength" --include="*.py"  # Backend
+
+# Compare model with database schema
+alembic check  # Python/Alembic
+npx prisma migrate status  # Node/Prisma
+```
+
+### Database-Model Mismatch
+
+```python
+# 🔴 BUG: Model has field, database doesn't
+class User(Base):
+    avatar_url = Column(String)  # 💀 Not in database!
+    
+# Error: column "avatar_url" does not exist
+
+# ✅ CORRECT: Always create migration first
+# 1. alembic revision --autogenerate -m "add avatar_url"
+# 2. alembic upgrade head
+# 3. Then add to model
+```
+
+### Field Alignment Checklist
+
+```markdown
+| Layer | Field Name | Type | Nullable |
+|-------|------------|------|----------|
+| Database | created_at | TIMESTAMP | NO |
+| ORM Model | created_at | DateTime | NO |
+| API Schema | createdAt | string | NO |
+| Frontend | createdAt | string | NO |
+```
+
+### Common Sync Issues
+
+```typescript
+// 🔴 BUG: Field name mismatch
+// Frontend expects: response.userId
+// Backend sends: response.user_id
+
+// ✅ CORRECT: Transform or match exactly
+const user = {
+    userId: response.user_id,  // Transform
+    ...response
+};
+```
+
+→ Complete database guide: `database-migration.md`
+
+---
+
+## 6. CORS Errors (Most Frustrating)
+
+### Why It Happens
+
+```
+Frontend (localhost:3000) → API (localhost:8000)
+Browser blocks because different origins!
+```
+
+### Common Symptoms
+
+```javascript
+// Console error
+Access to fetch at 'http://api.example.com/users' from origin 
+'http://localhost:3000' has been blocked by CORS policy
+```
+
+### Backend Fixes
+
+```python
+# Python FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["http://localhost:3000"],  # Not "*" in production!
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+```
+
+```javascript
+// Node.js Express
+const cors = require('cors');
+app.use(cors({
+    origin: 'http://localhost:3000',
+    credentials: true
+}));
+```
+
+### Checklist
+
+- [ ] Backend has CORS middleware configured
+- [ ] Allowed origins include frontend URL
+- [ ] Credentials setting matches frontend fetch options
+- [ ] Preflight OPTIONS requests handled
+- [ ] Custom headers allowed if using them
+
+---
+
+## 7. UI Boundary Detection (MANDATORY for Popups)
+
+### Why This Matters
+
+Popup elements (context menus, tooltips, dropdowns, popovers) positioned with raw click coordinates will be clipped/hidden when triggered near viewport edges. This is a **high-frequency bug** that affects user experience.
+
+### Detection Questions (Ask Before Every Popup Implementation)
+
+1. "If user clicks near viewport bottom, will the popup be fully visible?"
+2. "If user clicks near viewport right edge, will content overflow?"
+3. "Does the component have boundary flip logic?"
+
+### Universal Rule
+
+```
+❌ Bad:  style={{ left: clientX, top: clientY }}  // Direct coordinates
+✅ Good: useLayoutEffect → measure → clamp/flip → adjustedPosition
+```
+
+### Standard Implementation Pattern
+
+```tsx
+const [adjustedPos, setAdjustedPos] = useState({ x: 0, y: 0 });
+const menuRef = useRef<HTMLDivElement>(null);
+
+useLayoutEffect(() => {
+  if (!isOpen || !menuRef.current) return;
+  
+  const rect = menuRef.current.getBoundingClientRect();
+  const vh = window.innerHeight;
+  const vw = window.innerWidth;
+  const margin = 10; // Safety margin from edge
+  
+  let x = position.x;
+  let y = position.y;
+  
+  // Bottom boundary: flip upward
+  if (y + rect.height > vh - margin) {
+    y = y - rect.height;
+    if (y < margin) y = margin;
+  }
+  
+  // Right boundary: flip leftward
+  if (x + rect.width > vw - margin) {
+    x = x - rect.width;
+    if (x < margin) x = margin;
+  }
+  
+  setAdjustedPos({ x, y });
+}, [isOpen, position]);
+```
+
+### Component Types Requiring Boundary Detection
+
+| Component | Bottom Edge | Right Edge | Top Edge | Left Edge |
+|-----------|-------------|------------|----------|-----------|
+| Context Menu | Flip up | Flip left | Clamp | Clamp |
+| Tooltip | Flip up | Flip left | Flip down | Flip right |
+| Dropdown | Flip to "dropup" | Scroll/truncate | N/A | N/A |
+| Popover | Auto-flip | Auto-flip | Auto-flip | Auto-flip |
+| Autocomplete | Flip up | Scroll | N/A | N/A |
+
+### Pre-Implementation Checklist
+
+- [ ] Does the component use `fixed` or `absolute` positioning?
+- [ ] Is the position calculated from mouse coordinates (`clientX/Y`)?
+- [ ] Is there a `useLayoutEffect` for boundary detection?
+- [ ] Are all four edges (top/bottom/left/right) handled?
+- [ ] Is there a safety margin (8-10px) from viewport edges?
+
+### Hunt Similar Issues
+
+```bash
+# Find all popup positioning without boundary check
+grep -rn "clientX\|clientY\|pageX\|pageY" --include="*.tsx" -A 8 | \
+  grep -v "innerHeight\|innerWidth\|getBoundingClientRect"
+
+# Find fixed position elements
+grep -rn "position: fixed\|position: 'fixed'" --include="*.tsx" | \
+  grep -i "menu\|popup\|tooltip\|dropdown\|popover\|context"
+```
+
+### Recommended Libraries
+
+If implementing from scratch is complex, use battle-tested libraries:
+- **Floating UI** (`@floating-ui/react`) - Best flexibility
+- **Radix UI** - Built-in boundary handling
+- **Headless UI** - Accessible with boundary logic
+
+---
+
+## 8. React Hooks Common Mistakes
+
+### useEffect Mistakes (7 Critical)
+
+```typescript
+// ❌ 1. Missing dependency
+useEffect(() => {
+    fetchData(userId);  // userId not in deps
+}, []);  // 💀 Stale userId
+
+// ✅ Fix
+useEffect(() => {
+    fetchData(userId);
+}, [userId]);
+```
+
+```typescript
+// ❌ 2. Object/Array in deps (infinite loop)
+useEffect(() => {
+    doSomething();
+}, [{ id: 1 }]);  // 💀 New object every render
+
+// ✅ Fix: Use primitive or useMemo
+useEffect(() => {
+    doSomething();
+}, [id]);
+```
+
+```typescript
+// ❌ 3. Async function directly
+useEffect(async () => {  // 💀 Returns Promise, not cleanup
+    await fetchData();
+}, []);
+
+// ✅ Fix: Define async inside
+useEffect(() => {
+    const load = async () => {
+        await fetchData();
+    };
+    load();
+}, []);
+```
+
+```typescript
+// ❌ 4. Missing cleanup
+useEffect(() => {
+    const timer = setInterval(tick, 1000);
+    // 💀 Timer runs forever
+}, []);
+
+// ✅ Fix
+useEffect(() => {
+    const timer = setInterval(tick, 1000);
+    return () => clearInterval(timer);
+}, []);
+```
+
+```typescript
+// ❌ 5. Race condition
+useEffect(() => {
+    fetchData(id).then(setData);  // 💀 Old request may finish after new
+}, [id]);
+
+// ✅ Fix: Cancel flag
+useEffect(() => {
+    let cancelled = false;
+    fetchData(id).then(data => {
+        if (!cancelled) setData(data);
+    });
+    return () => { cancelled = true; };
+}, [id]);
+```
+
+### useState Mistakes
+
+```typescript
+// ❌ 1. Wrong initial type
+const [count, setCount] = useState(0);
+setCount("1");  // 💀 Type error
+
+// ❌ 2. Not using functional update
+setCount(count + 1);  // 💀 Stale if called multiple times
+setCount(prev => prev + 1);  // ✅
+
+// ❌ 3. Mutating state directly
+const [items, setItems] = useState([]);
+items.push(newItem);  // 💀 Mutation
+setItems([...items, newItem]);  // ✅
+
+// ❌ 4. Object mutation
+const [user, setUser] = useState({ name: '' });
+user.name = 'John';  // 💀 Mutation
+setUser({ ...user, name: 'John' });  // ✅
+```
+
+---
+
+## 8. API Error Handling (RFC 9457)
+
+### Standard Error Response Format
+
+```json
+{
+    "type": "https://api.example.com/errors/validation",
+    "title": "Validation Error",
+    "status": 422,
+    "detail": "The email field is invalid",
+    "instance": "/api/users/123",
+    "errors": {
+        "email": ["Invalid email format"],
+        "password": ["Must be at least 8 characters"]
+    }
+}
+```
+
+### HTTP Status Code Usage
+
+| Code | Meaning | When to Use |
+|------|---------|-------------|
+| 400 | Bad Request | Malformed JSON, missing required field |
+| 401 | Unauthorized | No token, invalid token |
+| 403 | Forbidden | Valid token, but no permission |
+| 404 | Not Found | Resource doesn't exist |
+| 409 | Conflict | Duplicate entry, version conflict |
+| 422 | Unprocessable | Valid syntax, invalid semantics (validation) |
+| 429 | Too Many Requests | Rate limited |
+| 500 | Server Error | Unexpected backend error |
+
+### Frontend Error Handling Pattern
+
+```typescript
+async function apiCall<T>(url: string): Promise<T> {
+    const response = await fetch(url);
+    
+    if (!response.ok) {
+        const error = await response.json();
+        
+        switch (response.status) {
+            case 401:
+                // Token expired, redirect to login
+                redirectToLogin();
+                throw new AuthError(error.detail);
+            
+            case 403:
+                throw new ForbiddenError(error.detail);
+            
+            case 404:
+                throw new NotFoundError(error.detail);
+            
+            case 422:
+                // Validation errors - show to user
+                throw new ValidationError(error.errors);
+            
+            case 429:
+                // Rate limited - retry after
+                throw new RateLimitError(response.headers.get('Retry-After'));
+            
+            default:
+                throw new ApiError(error.detail || 'Something went wrong');
+        }
+    }
+    
+    return response.json();
+}
+```
+
+---
+
+## 9. Input Validation (Security Critical)
+
+### Backend Validation (NEVER Trust Frontend)
+
+```python
+# ❌ BAD: Trust user input
+@app.post("/users")
+def create_user(data: dict):
+    db.execute(f"INSERT INTO users VALUES ('{data['email']}')")  # SQL Injection!
+
+# ✅ GOOD: Validate with schema
+from pydantic import BaseModel, EmailStr, Field
+
+class UserCreate(BaseModel):
+    email: EmailStr
+    password: str = Field(min_length=8, max_length=100)
+    name: str = Field(min_length=2, max_length=50)
+
+@app.post("/users")
+def create_user(data: UserCreate):  # Pydantic validates
+    db.add(User(**data.dict()))
+```
+
+### Frontend Validation (UX, not Security)
+
+```typescript
+// Validate before submit
+const validateForm = (data: FormData) => {
+    const errors: Record<string, string> = {};
+    
+    if (!data.email) {
+        errors.email = 'Email is required';
+    } else if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(data.email)) {
+        errors.email = 'Invalid email format';
+    }
+    
+    if (!data.password) {
+        errors.password = 'Password is required';
+    } else if (data.password.length < 8) {
+        errors.password = 'Password must be at least 8 characters';
+    }
+    
+    return errors;
+};
+```
+
+### Validation Alignment Checklist
+
+```markdown
+| Field | Frontend Rule | Backend Rule | Match? |
+|-------|---------------|--------------|--------|
+| email | Required, email format | Required, EmailStr | ✅ |
+| password | Min 8 chars | Min 8 chars | ✅ |
+| name | Max 100 chars | Max 50 chars | ❌ FE too lenient! |
+```
+
+---
+
+## 10. Backend Common Mistakes
+
+### Skipping Input Validation
+
+```python
+# 🔴 BUG: Direct user input to query
+query = f"SELECT * FROM users WHERE id = {request.id}"  # SQL Injection!
+
+# ✅ FIX: Parameterized query
+query = "SELECT * FROM users WHERE id = ?"
+db.execute(query, [request.id])
+```
+
+### Missing Rate Limiting
+
+```python
+# 🔴 BUG: No rate limiting
+@app.post("/login")
+def login(data: LoginRequest):
+    return authenticate(data)  # 💀 Brute force possible
+
+# ✅ FIX: Add rate limiter
+from slowapi import Limiter
+limiter = Limiter(key_func=get_remote_address)
+
+@app.post("/login")
+@limiter.limit("5/minute")
+def login(data: LoginRequest):
+    return authenticate(data)
+```
+
+### Exposing Sensitive Data in Logs
+
+```python
+# 🔴 BUG: Logging sensitive data
+logger.info(f"User login: {email}, password: {password}")  # 💀
+
+# ✅ FIX: Mask sensitive data
+logger.info(f"User login: {email}")
+```
+
+### Not Handling Concurrent Requests
+
+```python
+# 🔴 BUG: Race condition on balance update
+def withdraw(user_id, amount):
+    balance = get_balance(user_id)
+    if balance >= amount:
+        set_balance(user_id, balance - amount)  # 💀 Two requests can both pass
+
+# ✅ FIX: Use database transaction with lock
+async with db.transaction():
+    await db.execute("SELECT balance FROM accounts WHERE id = ? FOR UPDATE", [user_id])
+    # Now locked, proceed safely
+```
+
+---
+
+## 11. Solution Design Hierarchy (From bug-fixing)
+
+**Prefer top to bottom when fixing issues:**
+
+| Priority | Approach | When to Use |
+|----------|----------|-------------|
+| 1️⃣ | **Database field** | Feature can be configured per-entity |
+| 2️⃣ | **Runtime detection** | Feature can be probed at runtime |
+| 3️⃣ | **Config file** | Setting applies environment-wide |
+| 4️⃣ | **Pattern matching** | Fallback when detection impossible |
+| 5️⃣ | **Hardcoded list** | Last resort, document why |
+
+```python
+# ❌ BAD: Hardcoded list
+UNSUPPORTED = ["model-a", "model-b"]
+if name in UNSUPPORTED: fallback()
+
+# ✅ GOOD: Config-driven
+if not config.supports_feature: fallback()
+
+# ✅ GOOD: Runtime detection
+if not await detect_support(model): fallback()
+```
+
+---
+
+## 12. Similar Bug Hunt (MANDATORY After Any Fix)
+
+After fixing ANY bug, search the entire project:
+
+```bash
+# Extract the pattern that caused the bug
+grep -rn "PATTERN" --include="*.EXT" .
+```
+
+### Hunt Patterns
+
+| Bug Type | What to Search |
+|----------|----------------|
+| Hardcoded data | The exact hardcoded value |
+| Placeholder code | `TODO`, `FIXME`, empty handlers |
+| Missing integration | `handle*` functions without API calls |
+| Contract mismatch | Field name in both FE and BE |
+| State not synced | State init without fetch |
+
+### Report Format
+
+```markdown
+## Similar Bug Hunt
+
+**Pattern**: [What caused the bug]
+**Search**: `grep -rn "xxx" --include="*.ts"`
+
+| File | Line | Issue | Status |
+|------|------|-------|--------|
+| a.ts | 123 | Same pattern | ✅ Fixed |
+| b.ts | 45 | False positive | ⏭️ Skip |
+
+**Conclusion**: Found N similar issues, all fixed.
+```
+
+---
+
+## 13. Quick Detection Script
+
+```bash
+#!/bin/bash
+# Run before every commit
+
+echo "=== CORS Check ==="
+grep -rn "CORSMiddleware\|cors(" --include="*.py" --include="*.js" --include="*.ts"
+
+echo "=== Data Race Detection ==="
+grep -rn "self\.[a-z_]* = " --include="*.py" | grep -v "__init__"
+
+echo "=== Resource Leak Detection ==="
+grep -rn "useEffect" --include="*.tsx" -A 8 | grep -B 6 "}, \[\])" | grep -v "return () =>"
+
+echo "=== Missing Await ==="
+grep -rn "async function" --include="*.ts" -A 10 | grep -E "\([a-zA-Z]+\)\s*;" | grep -v await
+
+echo "=== Hardcoded Secrets ==="
+grep -rn "password\s*=\|api_key\s*=\|secret\s*=" --include="*.py" --include="*.ts" | grep -v "env\|config\|\.example"
+
+echo "=== SQL Injection Risk ==="
+grep -rn "execute.*f\"\|query.*\+" --include="*.py" --include="*.ts"
+
+echo "=== Missing Input Validation ==="
+grep -rn "@app\.\(post\|put\|patch\)" --include="*.py" -A 3 | grep -v "BaseModel\|Schema"
+
+echo "=== Done ==="
+```
+
+---
+
+## 14. Pre-Commit Checklist
+
+```markdown
+### Before Every Commit
+
+**🔴 Critical (Block Merge)**
+- [ ] CORS configured for frontend origin
+- [ ] All API inputs validated (Pydantic/Zod)
+- [ ] No SQL injection (parameterized queries)
+- [ ] No hardcoded secrets
+- [ ] Auth checked on protected endpoints
+
+**🟠 High Priority**
+- [ ] All useEffect have cleanup functions
+- [ ] All async operations awaited
+- [ ] No connection/timer leaks
+- [ ] Error boundaries for React components
+- [ ] Database migration created for schema changes
+
+**🟡 Medium Priority**
+- [ ] Field names match (FE/BE/DB)
+- [ ] All HTTP status codes handled (401, 403, 404, 422, 500)
+- [ ] Loading/error/empty states implemented
+- [ ] Form validation before submit
+- [ ] Double-submit prevention on forms
+
+**🟢 Good Practice**
+- [ ] No console.log/print debugging
+- [ ] Types on all functions
+- [ ] Similar bug hunt completed
+- [ ] API documented in Swagger
+
+### Quick Self-Test
+
+1. Does the feature work end-to-end? (smoke test)
+2. What happens on error? (error handling)
+3. What happens with no data? (empty state)
+4. What happens with slow network? (loading state)
+5. Can a user break it? (edge cases)
+```