@tinkcarlos/skillora 0.2.0

package/.claude/skills/code-review/references/overlooked-issues.md

@@ -0,0 +1,657 @@
+# Commonly Overlooked Issues - Detailed Guide
+
+Issues that developers often miss due to time pressure or experience gaps, leading to significantly higher maintenance costs later.
+
+---
+
+## Backend Commonly Overlooked Issues
+
+Backend issues often manifest in production under load, making them hard to catch locally. These issues account for ~40% of production bugs (2025 GitHub/SonarQube data).
+
+| Category | Overlooked Issue | Why Important | Example Bug |
+|----------|------------------|---------------|-------------|
+| **Error Handling** | Exception propagation & resource leak | 35% of production crashes | Java JDBC connection without finally, pool exhaustion |
+| **Security** | Injection attacks & hardcoded credentials | OWASP Top 1 risk | Python SQL without placeholder, API key in git |
+| **Performance** | N+1 queries & coarse lock granularity | 50% QPS drop under load | Hibernate loop load(), Go mutex on entire map |
+| **Concurrency** | Race condition & transaction isolation | Distributed system pain point | Node async parallel update shared state |
+| **Request Isolation** | Modifying shared/singleton objects | Data leak between users | `self.user_config.id = req.id` in Service |
+| **Data Validation** | Input boundary & serialization overflow | API abuse crashes | Python requests no size limit (DoS) |
+| **Logging** | Sensitive info leak & inconsistent log levels | Debug/audit difficulty | Go zapper logs full SQL, compliance violation |
+| **Compatibility** | Version dependencies & migration scripts | Multi-env deployment failure | npm audit vulnerabilities, Python 3.12 syntax in 3.8 |
+| **Maintainability** | Magic values & over-nested functions | High refactor cost | Go const not used, Java 10-layer nested if |
+| **Test Coverage** | Missing integration tests & incomplete mocks | CI green but prod red (25% regression bugs) | Python pytest only happy path |
+| **Configuration** | Env var override & hot update ignored | Zero-downtime deployment failure | Node process.env no fallback |
+
+### Backend Review Efficiency Tips
+
+- **Language Tool Stacks**: Java (Checkstyle+FindBugs), Node (StandardJS+David), Go (golangci-lint), Python (mypy+bandit)
+- **CI Integration**: Run SonarQube on every PR, automate >70% of checks
+- **Load Testing**: Use LoadForge/k6 for stress testing before production
+- **Priority**: Focus on API layer first, then infrastructure
+
+---
+
+## Frontend Commonly Overlooked Issues
+
+Frontend issues often appear only on specific devices, browsers, or network conditions. Visual issues require manual testing with only ~50% automation coverage. Responsive bugs account for ~35% of frontend issues (2025 data).
+
+| Category | Overlooked Issue | Why Important | Example Bug |
+|----------|------------------|---------------|-------------|
+| **UI Layout** | Responsive breakpoints & overflow hidden | Mobile = 60% traffic | iPad landscape sidebar overflow |
+| **Visual** | Dark mode & insufficient contrast | WCAG violation, poor UX | Light gray text on white (<3:1 ratio) |
+| **Interaction** | Focus management & keyboard navigation | Accessibility pain point | Modal tab key cannot focus switch |
+| **Functionality** | State sync & async error handling | Production network fluctuation | Page refresh shopping cart data lost |
+| **Memory Leaks** | Module-level variables & event listeners | SPA performance degradation | Global `const cache = {}` growing forever |
+| **TypeScript** | Missing `import type` & circular types | Runtime crash in bundlers | `import { Interface }` causes "no export" error |
+| **Performance** | Unoptimized images & JS render blocking | First load >3s = 50% user loss | Large image no lazy, LCP >4s |
+| **Compatibility** | Browser prefix & missing polyfill | Enterprise users on old browsers | Firefox flex-direction: row-reverse fails |
+| **Security/a11y** | Empty alt text & XSS injection | SEO & compliance risk | User uploads SVG with script tag |
+| **Code Standards** | Component props default & inconsistent naming | Reuse bugs | Button size="large" no default, renders small |
+| **Test Coverage** | Few E2E & outdated snapshots | UI change breaks easily | Design iteration, old snapshot false positive |
+| **Docs/Build** | Missing Storybook & ignored build warnings | Handoff difficult | PR merge, production build chunk too large |
+
+### Frontend Review Efficiency Tips
+
+- **Checklist Template**: Maintain "UI-Interaction-Code" checklist in Notion, tick before review
+- **Tool Stack**: Lighthouse (performance), axe (a11y), Cypress (E2E), Storybook (components)
+- **Cross-Team**: Designers participate in UI feedback; use Zeplin/Figma plugins for sync
+- **Balance**: Small changes focus on visual, large refactors focus on performance
+
+---
+
+## General Logic Errors
+
+## 1. Logic Errors
+
+### 1.1 Boundary Conditions - Account for 40% of Bugs
+
+**Check Points**:
+- [ ] null/undefined/None handling
+- [ ] Empty string "" handling
+- [ ] Empty array/collection [] handling
+- [ ] Zero values 0, 0.0, false handling
+- [ ] Max/Min integer values
+
+**Common Bug Examples**:
+
+```python
+# ❌ Empty list not checked
+def get_first(items):
+    return items[0]  # IndexError if empty
+
+# ✅ Correct handling
+def get_first(items):
+    if not items:
+        return None  # Or raise ValueError
+    return items[0]
+```
+
+```typescript
+// ❌ Undefined not checked
+function getUserName(user) {
+  return user.profile.name;  // Cannot read property 'name' of undefined
+}
+
+// ✅ Safe access
+function getUserName(user?: User): string | undefined {
+  return user?.profile?.name;
+}
+```
+
+### 1.2 Off-by-One Errors
+
+**Check Points**:
+- [ ] Loop start value (0 or 1)
+- [ ] Loop termination condition (< or <=)
+- [ ] Last element access (length-1)
+- [ ] String slice/substring
+
+**Common Bug Examples**:
+
+```python
+# ❌ Off-by-one: missing first element
+for i in range(1, len(arr)):
+    process(arr[i])
+
+# ❌ Off-by-one: processing one extra
+for i in range(len(arr) + 1):
+    process(arr[i])  # IndexError at last iteration
+
+# ✅ Correct
+for i in range(len(arr)):
+    process(arr[i])
+# Or more Pythonic:
+for item in arr:
+    process(item)
+```
+
+### 1.3 Floating Point Precision
+
+**Check Points**:
+- [ ] Use Decimal for currency calculations
+- [ ] Use tolerance for float comparison
+- [ ] Avoid floats as loop counters
+
+```python
+# ❌ Float precision issue
+if 0.1 + 0.2 == 0.3:  # False!
+    print("equal")
+
+# ✅ Use Decimal or tolerance comparison
+from decimal import Decimal
+if Decimal('0.1') + Decimal('0.2') == Decimal('0.3'):  # True
+    print("equal")
+
+# Or
+import math
+if math.isclose(0.1 + 0.2, 0.3):
+    print("equal")
+```
+
+---
+
+## 2. Error Handling
+
+### 2.1 Swallowed Exceptions
+
+**Check Points**:
+- [ ] Logging after catch
+- [ ] Re-throw or wrap exception
+- [ ] Return meaningful error info
+
+```python
+# ❌ Swallowed exception
+try:
+    risky_operation()
+except Exception:
+    pass  # Does nothing
+
+# ❌ Print only, no handling
+try:
+    risky_operation()
+except Exception as e:
+    print(e)  # Continues execution, may cause worse issues
+
+# ✅ Correct handling
+try:
+    risky_operation()
+except SpecificError as e:
+    logger.error(f"Operation failed: {e}", exc_info=True)
+    raise OperationFailedError(f"Cannot complete: {e}") from e
+```
+
+### 2.2 Resource Leaks
+
+**Check Points**:
+- [ ] File handles closed
+- [ ] Database connections released
+- [ ] Network connections closed
+- [ ] Locks released
+
+```python
+# ❌ Resource leak
+def read_file(path):
+    f = open(path)
+    data = f.read()
+    # If exception here, f is never closed
+    return data
+
+# ✅ Use context manager
+def read_file(path):
+    with open(path) as f:
+        return f.read()
+
+# ✅ Or try-finally
+def read_file(path):
+    f = open(path)
+    try:
+        return f.read()
+    finally:
+        f.close()
+```
+
+### 2.3 Network Timeout
+
+**Check Points**:
+- [ ] HTTP requests have timeout
+- [ ] Database queries have timeout
+- [ ] Retry mechanism exists
+- [ ] Retry has exponential backoff
+
+```python
+# ❌ No timeout - may block forever
+response = requests.get(url)
+
+# ✅ Set timeout
+response = requests.get(url, timeout=30)
+
+# ✅ Request with retry
+from tenacity import retry, stop_after_attempt, wait_exponential
+
+@retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=1, max=10))
+def fetch_with_retry(url):
+    return requests.get(url, timeout=30)
+```
+
+---
+
+## 3. Input Validation
+
+### 3.1 SQL Injection
+
+**Check Points**:
+- [ ] All SQL uses parameterized queries
+- [ ] No string concatenation for SQL
+- [ ] ORM query params not directly concatenated
+
+```python
+# ❌ SQL injection
+def get_user(user_id):
+    cursor.execute(f"SELECT * FROM users WHERE id = '{user_id}'")
+    # Input: "'; DROP TABLE users; --"
+
+# ✅ Parameterized query
+def get_user(user_id):
+    cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,))
+
+# ✅ ORM
+def get_user(user_id):
+    return User.objects.get(id=user_id)
+```
+
+### 3.2 XSS Attack
+
+**Check Points**:
+- [ ] User input escaped before output
+- [ ] Using secure template engine
+- [ ] innerHTML doesn't handle untrusted data
+
+```typescript
+// ❌ XSS risk
+element.innerHTML = userInput;  // User can inject <script>alert('XSS')</script>
+
+// ✅ Use textContent
+element.textContent = userInput;
+
+// ✅ Or use DOMPurify
+import DOMPurify from 'dompurify';
+element.innerHTML = DOMPurify.sanitize(userInput);
+```
+
+### 3.3 Type Validation
+
+**Check Points**:
+- [ ] External input type validated
+- [ ] API params have schema validation
+- [ ] Type conversion is safe
+
+```python
+# ❌ Type not validated
+def process_age(age):
+    return age + 1  # What if age is string?
+
+# ✅ Type validation
+def process_age(age: int) -> int:
+    if not isinstance(age, int):
+        raise TypeError(f"Expected int, got {type(age)}")
+    if age < 0 or age > 150:
+        raise ValueError(f"Invalid age: {age}")
+    return age + 1
+
+# ✅ Use Pydantic
+from pydantic import BaseModel, Field
+
+class UserInput(BaseModel):
+    age: int = Field(ge=0, le=150)
+```
+
+---
+
+## 4. Performance Bottlenecks
+
+### 4.1 N+1 Queries
+
+**Check Points**:
+- [ ] No database query in loop
+- [ ] Use batch queries
+- [ ] ORM uses select_related/prefetch_related
+
+```python
+# ❌ N+1 query - 100 users = 101 queries
+users = User.objects.all()
+for user in users:
+    print(user.profile.bio)  # Each profile access triggers a query
+
+# ✅ Eager load related data - only 2 queries
+users = User.objects.select_related('profile').all()
+for user in users:
+    print(user.profile.bio)
+
+# ✅ Many-to-many use prefetch_related
+users = User.objects.prefetch_related('posts').all()
+```
+
+### 4.2 String Concatenation
+
+**Check Points**:
+- [ ] No + concatenation in loops
+- [ ] Use StringBuilder/join
+
+```python
+# ❌ O(n²) string concatenation
+result = ""
+for item in items:
+    result += str(item)  # Creates new string each time
+
+# ✅ O(n) using join
+result = "".join(str(item) for item in items)
+
+# ✅ Use StringIO
+from io import StringIO
+buffer = StringIO()
+for item in items:
+    buffer.write(str(item))
+result = buffer.getvalue()
+```
+
+### 4.3 Time Complexity
+
+**Check Points**:
+- [ ] Any nested loops that can be optimized
+- [ ] Can use Set/Dict for lookups
+- [ ] Is sorting necessary, can use heap
+
+```python
+# ❌ O(n²) - nested loop lookup
+def find_common(list1, list2):
+    common = []
+    for item in list1:
+        if item in list2:  # O(n) lookup
+            common.append(item)
+    return common
+
+# ✅ O(n) - use Set
+def find_common(list1, list2):
+    set2 = set(list2)  # O(n) build
+    return [item for item in list1 if item in set2]  # O(1) lookup
+```
+
+---
+
+## 5. Security
+
+### 5.1 Hardcoded Credentials
+
+**Check Points**:
+- [ ] No API keys, passwords, tokens in source
+- [ ] Config files not in version control
+- [ ] Use environment variables or secret manager
+
+```python
+# ❌ Hardcoded
+API_KEY = "sk-1234567890abcdef"
+DB_PASSWORD = "admin123"
+
+# ✅ Use environment variables
+import os
+API_KEY = os.environ.get("API_KEY")
+if not API_KEY:
+    raise ValueError("API_KEY environment variable required")
+
+# ✅ Use Secret Manager
+from google.cloud import secretmanager
+client = secretmanager.SecretManagerServiceClient()
+API_KEY = client.access_secret_version(name="projects/.../secrets/api-key/versions/latest")
+```
+
+### 5.2 Permission Checks
+
+**Check Points**:
+- [ ] Permission check before each sensitive operation
+- [ ] Resource ownership verified
+- [ ] Prevent privilege escalation
+
+```python
+# ❌ No permission check
+@app.get("/users/{user_id}/data")
+async def get_user_data(user_id: str):
+    return await db.get_user_data(user_id)  # Anyone can access any user data
+
+# ✅ Check permissions
+@app.get("/users/{user_id}/data")
+async def get_user_data(user_id: str, current_user: User = Depends(get_current_user)):
+    if current_user.id != user_id and not current_user.is_admin:
+        raise HTTPException(status_code=403, detail="Access denied")
+    return await db.get_user_data(user_id)
+```
+
+### 5.3 Sensitive Information in Logs
+
+**Check Points**:
+- [ ] No passwords or tokens in logs
+- [ ] No complete credit card numbers in logs
+- [ ] No PII (Personally Identifiable Information)
+
+```python
+# ❌ Sensitive info leakage
+logger.info(f"User login: {username}, password: {password}")
+logger.debug(f"Request: {request.json()}")  # May contain sensitive data
+
+# ✅ Secure logging
+logger.info(f"User login: {username}")
+logger.debug(f"Request to {request.path}, user: {current_user.id}")
+```
+
+---
+
+## 6. Concurrency Issues
+
+### 6.1 Race Conditions
+
+**Check Points**:
+- [ ] Shared state protected
+- [ ] Read-modify-write operations atomic
+- [ ] Appropriate locks used
+
+```python
+# ❌ Race condition
+class Counter:
+    def __init__(self):
+        self.count = 0
+    
+    def increment(self):
+        self.count += 1  # Read-modify-write not atomic
+
+# ✅ Use lock
+import threading
+
+class Counter:
+    def __init__(self):
+        self.count = 0
+        self._lock = threading.Lock()
+    
+    def increment(self):
+        with self._lock:
+            self.count += 1
+```
+
+### 6.2 Deadlock
+
+**Check Points**:
+- [ ] Multiple locks acquired in fixed order
+- [ ] Lock acquisition has timeout
+- [ ] No circular dependencies
+
+```python
+# ❌ Possible deadlock
+def transfer_a_to_b():
+    with lock_a:
+        with lock_b:
+            # transfer
+
+def transfer_b_to_a():
+    with lock_b:
+        with lock_a:
+            # transfer
+
+# ✅ Fixed order lock acquisition
+def transfer(from_account, to_account):
+    lock1, lock2 = sorted([from_account.lock, to_account.lock], key=id)
+    with lock1:
+        with lock2:
+            # transfer
+```
+
+### 6.3 Async Pitfalls
+
+**Check Points**:
+- [ ] No blocking calls in async functions
+- [ ] await used correctly
+- [ ] Promise handles reject
+
+```python
+# ❌ Blocking in async
+async def fetch_data():
+    time.sleep(5)  # Blocks entire event loop!
+    return await some_async_call()
+
+# ✅ Use async sleep
+async def fetch_data():
+    await asyncio.sleep(5)
+    return await some_async_call()
+
+# ❌ Blocking I/O
+async def read_file():
+    with open("file.txt") as f:  # Blocking!
+        return f.read()
+
+# ✅ Use aiofiles
+import aiofiles
+async def read_file():
+    async with aiofiles.open("file.txt") as f:
+        return await f.read()
+```
+
+```typescript
+// ❌ Promise not handling reject
+fetch('/api/data').then(r => r.json());
+
+// ✅ Handle error
+fetch('/api/data')
+  .then(r => r.json())
+  .catch(error => {
+    console.error('Fetch failed:', error);
+    throw error;
+  });
+
+// ✅ Use async/await
+try {
+  const response = await fetch('/api/data');
+  return await response.json();
+} catch (error) {
+  console.error('Fetch failed:', error);
+  throw error;
+}
+```
+
+---
+
+## 7. Framework-Specific Pitfalls
+
+### React
+
+| Pitfall | Check Points | Example |
+|---------|--------------|---------|
+| Non-unique key | Is key unique and stable in lists | `key={index}` causes render issues |
+| useEffect deps | Is dependency array complete | Missing deps causes stale closure |
+| Infinite loop | setState in useEffect | No deps array causes loop |
+| Memory leak | Clean up subscriptions and timers | Continues after unmount |
+
+```tsx
+// ❌ Key using index
+{items.map((item, index) => (
+  <Item key={index} data={item} />  // Issues on delete/sort
+))}
+
+// ✅ Use unique ID
+{items.map(item => (
+  <Item key={item.id} data={item} />
+))}
+
+// ❌ Incomplete useEffect deps
+useEffect(() => {
+  fetchUser(userId);
+}, []);  // Missing userId
+
+// ✅ Complete deps
+useEffect(() => {
+  fetchUser(userId);
+}, [userId]);
+```
+
+### Vue
+
+| Pitfall | Check Points | Example |
+|---------|--------------|---------|
+| v-if/v-for order | v-if should be outer | Together causes performance issue |
+| Reactivity lost | Is object property reactive | Direct new property not reactive |
+| this context | Arrow function this | Cannot access component this |
+
+```vue
+<!-- ❌ v-for with v-if together -->
+<li v-for="user in users" v-if="user.active">
+
+<!-- ✅ Use computed to filter -->
+<li v-for="user in activeUsers">
+```
+
+### Django
+
+| Pitfall | Check Points | Example |
+|---------|--------------|---------|
+| N+1 queries | Use select_related | Accessing FK in loop |
+| Unvalidated input | Form/Serializer validation | Direct request.POST usage |
+| Password storage | Use make_password | Plaintext password storage |
+
+### FastAPI
+
+| Pitfall | Check Points | Example |
+|---------|--------------|---------|
+| Sync blocking | No sync I/O in async | Using requests instead of httpx |
+| Dependency injection | Depends used correctly | Dependency not declared |
+| CORS | CORS configured | Frontend cannot access |
+
+---
+
+## Quick Self-Check List
+
+When reviewing each file, quickly check:
+
+```markdown
+## Quick Self-Check (Per File)
+
+### Boundary Handling
+- [ ] null/empty value handling
+- [ ] Array bounds
+- [ ] Type conversion
+
+### Error Handling
+- [ ] try-catch complete
+- [ ] Resource cleanup (finally)
+- [ ] Exception logging
+
+### Security
+- [ ] No hardcoded credentials
+- [ ] Input validation
+- [ ] Permission checks
+
+### Performance
+- [ ] No N+1 queries
+- [ ] No O(n²) nested loops
+- [ ] String handling optimized
+
+### Concurrency
+- [ ] Shared state protected
+- [ ] async/await correct
+- [ ] No blocking calls
+```