@tinkcarlos/skillora 0.2.0

package/.claude/skills/code-review/references/hidden-bugs-detection.md

@@ -0,0 +1,473 @@
+# Hidden Bug Deep Detection Guide
+
+> Specifically designed to discover hidden bugs that are difficult to find through conventional code review.
+
+## Table of Contents
+
+- [Hidden Bug Categories](#hidden-bug-categories)
+- [Data Race Detection](#1-data-race-detection)
+- [Memory & Resource Leaks](#2-memory--resource-leaks)
+- [State Inconsistency Issues](#3-state-inconsistency-issues)
+- [Timing & Concurrency Traps](#4-timing--concurrency-traps)
+- [Frontend-Backend Coupling Hidden Issues](#5-frontend-backend-coupling-hidden-issues)
+- [Automated Detection Commands](#automated-detection-commands)
+
+---
+
+## Hidden Bug Categories
+
+| Category | Characteristics | Discovery 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 |
+| **Boundary Overflow** | Triggered by extreme input | 🟡 Medium | 🟠 High |
+| **Resource Leaks** | Uncleared on exception paths | 🟡 Medium | 🟠 High |
+
+---
+
+## 1. Data Race Detection
+
+### 1.1 Shared State Modification (Most Dangerous Hidden Bug)
+
+**Required patterns to check**:
+
+```python
+# 🔴 Hidden Bug: Modifying shared object in Service singleton
+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  # 💀 Critical! Affects other users
+        await self.executor.run(self.agent, user_input)
+```
+
+**Detection method**:
+
+```bash
+# Python: Search for all self.xxx = in async functions
+grep -rn "self\.[a-z_]* = " --include="*.py" | grep -E "(async def|await)"
+
+# Search for property modifications in singleton patterns
+grep -rn "@singleton\|Singleton\|_instance" --include="*.py" -A 20 | grep "self\."
+```
+
+**Safe pattern**:
+
+```python
+# ✅ Correct: Pass through parameters, don't modify shared state
+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 instead of modifying
+    )
+```
+
+### 1.2 Global Variables/Module-Level Cache
+
+```python
+# 🔴 Hidden Bug: Module-level dict modified concurrently
+_cache = {}  # Module-level, shared by all requests
+
+async def get_user(user_id):
+    if user_id not in _cache:
+        _cache[user_id] = await db.fetch(user_id)  # Race condition!
+    return _cache[user_id]
+```
+
+**Detection command**:
+
+```bash
+# Find all module-level mutable objects
+grep -rn "^[a-z_]* = \[\]\|^[a-z_]* = {}\|^[a-z_]* = set()" --include="*.py"
+```
+
+### 1.3 Go Language Specific Detection
+
+```bash
+# Go race detector (MUST run)
+go test -race ./...
+
+# Search for unprotected shared variables
+grep -rn "var [a-z]" --include="*.go" | grep -v "sync\."
+```
+
+---
+
+## 2. Memory & Resource Leaks
+
+### 2.1 Event Listener Leaks (Most Common in Frontend)
+
+```typescript
+// 🔴 Hidden Bug: useEffect without cleanup
+useEffect(() => {
+    window.addEventListener('resize', handleResize);
+    // 💀 Listener persists after component unmount, memory leak
+}, []);
+
+// ✅ Correct
+useEffect(() => {
+    window.addEventListener('resize', handleResize);
+    return () => window.removeEventListener('resize', handleResize);
+}, []);
+```
+
+**Detection command**:
+
+```bash
+# Search for useEffect without return
+grep -rn "useEffect" --include="*.tsx" --include="*.ts" -A 10 | grep -B 5 "\\[\\])" | grep -v "return"
+```
+
+### 2.2 Timer Leaks
+
+```typescript
+// 🔴 Hidden Bug: setInterval not cleared
+useEffect(() => {
+    const timer = setInterval(fetchData, 5000);
+    // 💀 Still executing after component unmount
+}, []);
+```
+
+**Detection command**:
+
+```bash
+# Search for setInterval/setTimeout, check if clearInterval/clearTimeout exists
+grep -rn "setInterval\|setTimeout" --include="*.ts" --include="*.tsx" -B 2 -A 5
+```
+
+### 2.3 Database Connection Leaks
+
+```python
+# 🔴 Hidden Bug: Connection not closed on exception path
+async def query_data():
+    conn = await pool.acquire()
+    result = await conn.fetch("SELECT ...")  # If exception thrown here
+    await pool.release(conn)  # 💀 Never executed
+    return result
+
+# ✅ Correct: Use context manager
+async def query_data():
+    async with pool.acquire() as conn:
+        return await conn.fetch("SELECT ...")
+```
+
+**Detection command**:
+
+```bash
+# Search for acquire/open not in with statement
+grep -rn "\.acquire()\|\.open(" --include="*.py" | grep -v "with\|async with"
+```
+
+### 2.4 Closure Reference Leaks
+
+```javascript
+// 🔴 Hidden Bug: Closure holds reference to large object
+function createHandler() {
+    const hugeData = loadHugeData();  // 10MB data
+    return function handler() {
+        console.log(hugeData.length);  // Closure holds hugeData reference
+        // 💀 Even if hugeData is no longer needed, cannot be GC'd
+    };
+}
+```
+
+---
+
+## 3. State Inconsistency Issues
+
+### 3.1 Optimistic Update Rollback Failure
+
+```typescript
+// 🔴 Hidden Bug: State inconsistency after optimistic update failure
+const [items, setItems] = useState([]);
+
+async function deleteItem(id) {
+    const backup = [...items];
+    setItems(items.filter(i => i.id !== id));  // Optimistic update
+    
+    try {
+        await api.delete(id);
+    } catch (e) {
+        // 💀 If other operations modified items simultaneously, rollback overwrites
+        setItems(backup);
+    }
+}
+```
+
+### 3.2 Cache & Database Inconsistency
+
+```python
+# 🔴 Hidden Bug: Update order causes inconsistency
+async def update_user(user_id, data):
+    await cache.delete(f"user:{user_id}")  # 1. Delete cache first
+    await db.update(user_id, data)          # 2. Then update DB
+    # 💀 If read request between 1-2, old data written to cache
+
+# ✅ Correct: Update DB first, then delete cache (or use delayed double-delete)
+async def update_user(user_id, data):
+    await db.update(user_id, data)
+    await cache.delete(f"user:{user_id}")
+    await asyncio.sleep(0.5)  # Delay
+    await cache.delete(f"user:{user_id}")  # Double delete
+```
+
+### 3.3 Distributed Transaction Inconsistency
+
+```python
+# 🔴 Hidden Bug: Cross-service operations without transaction guarantee
+async def create_order(data):
+    order = await order_service.create(data)      # 1. Create order
+    await payment_service.charge(order.total)     # 2. Charge payment
+    await inventory_service.reduce(order.items)   # 3. Reduce inventory
+    # 💀 If step 3 fails, order created, payment charged, but inventory not reduced
+```
+
+**Detection method**:
+
+```bash
+# Search for cross-service call sequences
+grep -rn "await.*_service\." --include="*.py" -A 3 | grep -E "_service\.[a-z]+\("
+```
+
+---
+
+## 4. Timing & Concurrency Traps
+
+### 4.1 Async Operation Order Dependency
+
+```typescript
+// 🔴 Hidden Bug: Depends on execution order but not guaranteed
+async function loadData() {
+    fetchUserProfile();  // Async but not awaited
+    fetchUserOrders();   // Async but not awaited
+    // 💀 Completion order uncertain, errors if there are dependencies
+}
+```
+
+**Detection command**:
+
+```bash
+# Search for async function calls without await
+grep -rn "async function\|async \(" --include="*.ts" -l | xargs grep -n "([a-zA-Z]*)\s*;" | grep -v await
+```
+
+### 4.2 Promise.all Partial Failure
+
+```typescript
+// 🔴 Hidden Bug: One failure causes all to fail
+async function loadAllData() {
+    const [users, orders, products] = await Promise.all([
+        fetchUsers(),
+        fetchOrders(),
+        fetchProducts()
+    ]);
+    // 💀 If fetchOrders fails, successful results for users and products also lost
+}
+
+// ✅ Correct: Use Promise.allSettled
+async function loadAllData() {
+    const results = await Promise.allSettled([
+        fetchUsers(),
+        fetchOrders(),
+        fetchProducts()
+    ]);
+    // Can handle successful and failed results separately
+}
+```
+
+### 4.3 React 18 Concurrent Mode Traps
+
+```typescript
+// 🔴 Hidden Bug: Code that depends on render order
+useEffect(() => {
+    globalState.currentUser = user;  // 💀 Executes twice in StrictMode
+}, [user]);
+
+// ✅ Correct: Use React state management
+const [currentUser, setCurrentUser] = useState(user);
+```
+
+---
+
+## 5. Frontend-Backend Coupling Hidden Issues
+
+### 5.1 WebSocket State Desync
+
+```typescript
+// 🔴 Hidden Bug: State desync after reconnection
+const ws = new WebSocket(url);
+ws.onmessage = (event) => {
+    updateState(event.data);  // Incremental update
+};
+ws.onopen = () => {
+    // 💀 Continues incremental update after reconnect, but missed messages during disconnect
+};
+
+// ✅ Correct: Request full state after reconnect
+ws.onopen = () => {
+    ws.send(JSON.stringify({ type: 'SYNC_FULL_STATE' }));
+};
+```
+
+### 5.2 Token Refresh Race
+
+```typescript
+// 🔴 Hidden Bug: Multiple requests triggering token refresh simultaneously
+async function apiCall(url) {
+    if (isTokenExpired()) {
+        await refreshToken();  // 💀 Multiple requests enter simultaneously, multiple refreshes
+    }
+    return fetch(url);
+}
+
+// ✅ Correct: Use refresh lock
+let refreshPromise = null;
+async function apiCall(url) {
+    if (isTokenExpired()) {
+        if (!refreshPromise) {
+            refreshPromise = refreshToken().finally(() => {
+                refreshPromise = null;
+            });
+        }
+        await refreshPromise;
+    }
+    return fetch(url);
+}
+```
+
+### 5.3 Pagination Data Drift
+
+```typescript
+// 🔴 Hidden Bug: Data changed while loading next page
+// Page 1 loads with 100 items
+// New data inserted before loading page 2
+// 💀 Page 2 may duplicate last few items from page 1
+
+// ✅ Correct: Use cursor pagination
+async function loadMore(cursor) {
+    return api.get(`/items?after=${cursor}&limit=20`);
+}
+```
+
+### 5.4 Optimistic UI vs Server Validation Conflict
+
+```typescript
+// 🔴 Hidden Bug: Frontend allows but backend rejects
+// Frontend validation: title length < 200
+// Backend validation: title length < 100
+// 💀 User inputs 150 chars, frontend shows success, backend returns 400
+```
+
+**Detection method**:
+
+```bash
+# Compare frontend and backend validation rules
+# Frontend
+grep -rn "maxLength\|max:\|\.length <" --include="*.ts" --include="*.tsx"
+# Backend
+grep -rn "max_length\|Field.*le=\|MaxLength" --include="*.py"
+```
+
+---
+
+## Automated Detection Commands
+
+### One-Click Detection Script
+
+```bash
+#!/bin/bash
+# hidden-bug-scan.sh - Hidden Bug Auto Scanner
+
+echo "=== 1. Data Race Detection ==="
+echo "--- Singleton state modification ---"
+grep -rn "self\.[a-z_]* = " --include="*.py" | grep -v "__init__\|def __"
+
+echo ""
+echo "--- Module-level mutable objects ---"
+grep -rn "^[a-z_]* = \[\]\|^[a-z_]* = {}" --include="*.py"
+
+echo ""
+echo "=== 2. Resource Leak Detection ==="
+echo "--- Uncleaned useEffect ---"
+grep -rn "useEffect" --include="*.tsx" -A 8 | grep -B 6 "\\[\\])" | grep -v "return () =>"
+
+echo ""
+echo "--- Unclosed connections ---"
+grep -rn "\.acquire()\|\.open(" --include="*.py" | grep -v "with\|async with"
+
+echo ""
+echo "=== 3. Concurrency Issue Detection ==="
+echo "--- Unawaited async calls ---"
+grep -rn "async function" --include="*.ts" -A 20 | grep -E "\([a-zA-Z]+\)\s*;$" | grep -v await
+
+echo ""
+echo "=== 4. Security Issue Detection ==="
+echo "--- Hardcoded credentials ---"
+grep -rn "password\s*=\|api_key\s*=\|secret\s*=" --include="*.py" --include="*.ts" | grep -v "os.environ\|process.env"
+
+echo ""
+echo "=== Detection Complete ==="
+```
+
+### Python Specific Detection
+
+```bash
+# Data race
+python -m bandit -r src/
+go test -race ./...  # Go
+
+# Memory leak
+python -m memory_profiler script.py
+```
+
+### Frontend Specific Detection
+
+```bash
+# React Hook rules
+npx eslint . --rule 'react-hooks/exhaustive-deps: error'
+
+# Memory leak
+# Chrome DevTools → Memory → Heap snapshot
+```
+
+---
+
+## Hidden Bug Checklist
+
+Required checks for every Code Review:
+
+```markdown
+## Hidden Bug Checklist
+
+### Data Races
+- [ ] Is shared state modified in singleton Services
+- [ ] Are module-level variables accessed concurrently
+- [ ] Are there unprotected global caches
+
+### Resource Leaks
+- [ ] Does useEffect have cleanup function
+- [ ] Is setInterval/setTimeout cleared
+- [ ] Are database/network connections properly closed
+- [ ] Are event listeners removed
+
+### State Inconsistency
+- [ ] Is cache update order correct
+- [ ] Is optimistic update failure properly rolled back
+- [ ] Do cross-service operations have transaction guarantees
+
+### Timing Issues
+- [ ] Are async operations properly awaited
+- [ ] Does Promise.all handle partial failures
+- [ ] Do concurrent requests have race conditions
+
+### Frontend-Backend Coupling
+- [ ] Are frontend/backend validation rules consistent
+- [ ] Does WebSocket reconnection sync state
+- [ ] Does Token refresh have race protection
+- [ ] Does pagination use cursor to prevent data drift
+```

package/.claude/skills/code-review/references/ide-lint-errors-guide.md

@@ -0,0 +1,173 @@
+# IDE Lint Errors Detection and Resolution Guide
+
+IDE red squiggly lines (lint errors) indicate code quality issues that must be identified and addressed during code review. This guide provides a systematic approach to detecting, categorizing, and requiring fixes for these errors.
+
+## Overview
+
+Red underlines in code editors represent diagnostics from language servers, linters, and type checkers. During code review, these errors are automatic P1 findings — code with red underlines should not be approved.
+
+## Error Categories
+
+### 1. Syntax Errors (P0 - Blocker)
+
+**Review Impact**: Code will not compile/run. Automatic BLOCKED verdict.
+
+| Common Causes | Detection | Required Action |
+|---------------|-----------|-----------------|
+| Missing semicolons, commas, colons | Parser error at specific line | Require fix before approval |
+| Unmatched brackets/braces/parentheses | Error often at end of block | Require fix |
+| Typos in keywords (`fucntion`, `retrun`) | "Unknown identifier" error | Require fix |
+| Invalid syntax constructs | "Unexpected token" error | Require fix |
+
+### 2. Type Errors (P0/P1 - Must Fix)
+
+**Review Impact**: Runtime type errors, undefined behavior. P0 if in critical path.
+
+| Common Causes | Detection | Required Action |
+|---------------|-----------|-----------------|
+| Type mismatch in assignment | "Type X not assignable to Y" | Require fix or justified cast |
+| Undefined type reference | "Cannot find type X" | Require import or definition |
+| Wrong generic parameters | "Expected N type arguments" | Require fix |
+| Null/undefined not handled | "Object possibly undefined" | Require null check |
+| Incorrect function return type | "Return type mismatch" | Require fix |
+
+### 3. Import/Module Errors (P1 - Must Fix)
+
+**Review Impact**: Module resolution failures at runtime or build.
+
+| Common Causes | Detection | Required Action |
+|---------------|-----------|-----------------|
+| Missing import statement | "X is not defined" | Require import |
+| Wrong import path | "Cannot find module X" | Require path fix |
+| Circular dependencies | Complex error pattern | Require refactor |
+| Package not installed | "Cannot find module X" | Require package installation |
+| Wrong export/import style | "X has no default export" | Require matching import |
+
+### 4. Linting Rule Violations (P2/P3 - Should Fix)
+
+**Review Impact**: Code quality, maintainability. P2 for safety rules.
+
+| Common Causes | Detection | Required Action |
+|---------------|-----------|-----------------|
+| Unused variables/imports | "X is defined but never used" | Recommend removal |
+| Code style violations | Various formatting warnings | Recommend fix |
+| Deprecated API usage | "X is deprecated" | Recommend update |
+| Unsafe patterns | Security/safety warnings | P1 if security-related |
+| Complexity warnings | "Function too complex" | Recommend refactor |
+
+### 5. Declaration Errors (P1 - Must Fix)
+
+**Review Impact**: Runtime ReferenceError, undefined behavior.
+
+| Common Causes | Detection | Required Action |
+|---------------|-----------|-----------------|
+| Using before declaration | "X used before defined" | Require reorder |
+| Missing variable declaration | "X is not defined" | Require declaration |
+| Scope issues | "X is not accessible" | Require scope fix |
+| Missing function definition | "X is not a function" | Require definition |
+
+### 6. Configuration Issues (P1 - Must Fix)
+
+**Review Impact**: Project-wide build/type failures.
+
+| Common Causes | Detection | Required Action |
+|---------------|-----------|-----------------|
+| Missing tsconfig.json | TypeScript errors everywhere | Require config |
+| Wrong compiler options | Unexpected type behavior | Require config fix |
+| Missing type definitions | "Cannot find type X" for packages | Require @types install |
+| Linter misconfiguration | Inconsistent linting | Require config fix |
+| Python venv issues | Import errors for packages | Require env fix |
+
+## Review Workflow Integration
+
+### Phase 1.1: IDE Lint Error Analysis (MANDATORY)
+
+**Before manual code review, run automated lint check:**
+
+```
+read_lints(paths: ["path/to/changed/files"])
+```
+
+**Categorize findings by severity:**
+
+| Category | Finding Level | Review Action |
+|----------|---------------|---------------|
+| Syntax errors | P0 | BLOCKED — cannot approve |
+| Type errors (critical path) | P0 | BLOCKED — require fix |
+| Type errors (non-critical) | P1 | CHANGES REQUESTED |
+| Import/declaration errors | P1 | CHANGES REQUESTED |
+| Config issues | P1 | CHANGES REQUESTED |
+| Linting warnings (safety) | P2 | Should fix or justify |
+| Linting warnings (style) | P3 | Optional fix |
+
+### Lint Error Findings Template
+
+```markdown
+## IDE Lint Error Findings
+
+| File | Line | Error Type | Message | Severity |
+|------|------|------------|---------|----------|
+| src/component.tsx | 42 | Type | "Property 'X' does not exist" | P1 |
+| src/utils.ts | 15 | Import | "Cannot find module 'Y'" | P1 |
+| ... | ... | ... | ... | ... |
+
+**Required Actions:**
+- [ ] Fix all P0/P1 lint errors before re-review
+- [ ] Document any intentional suppressions
+```
+
+## Common Patterns to Flag
+
+### High-Risk Lint Errors (Always P1+)
+
+| Pattern | Why It's High-Risk | Review Action |
+|---------|-------------------|---------------|
+| any type usage | Bypasses type safety | Require specific type |
+| Ignored Promise | Unhandled async error | Require await/catch |
+| Non-null assertion (!) | Hides null checks | Require proper check |
+| Type assertion (as X) | May hide mismatch | Verify correctness |
+| @ts-ignore / # type: ignore | Suppresses errors | Require justification |
+| Unused catch variable | May hide error info | Require logging |
+
+### Patterns That Indicate Deeper Issues
+
+| Lint Error Pattern | May Indicate | Follow-up Check |
+|-------------------|--------------|-----------------|
+| Many "X is not defined" | Missing module | Check package.json |
+| Type errors everywhere | Config issue | Check tsconfig |
+| Import path errors | Structure change | Check for refactor |
+| Unused exports | Dead code | Check for removal |
+
+## Verification Checklist for Reviewers
+
+Before approving ANY PR:
+
+- [ ] Run `read_lints` on all changed files
+- [ ] Zero P0 errors (syntax, critical type)
+- [ ] Zero P1 errors (imports, declarations, types)
+- [ ] P2 errors addressed or justified
+- [ ] No new lint errors compared to base branch
+- [ ] Suppressions have documented justification
+
+## Integration with Review Report
+
+Include lint error findings in the standard review report:
+
+```markdown
+## Phase 1: Automated Checks
+
+### Lint Error Analysis
+- Files checked: [list]
+- P0 errors: [count] — BLOCKING
+- P1 errors: [count] — Must fix
+- P2 errors: [count] — Should address
+- P3 errors: [count] — Optional
+
+### Required Before Approval
+1. Fix syntax error in file.ts:42
+2. Add missing import in utils.ts:15
+3. Address type mismatch in component.tsx:88
+```
+
+→ Return to main workflow: Phase 1 Automated Checks
+