@tinkcarlos/skillora 0.2.0

package/.claude/skills/code-review/references/batch-processing-strategy.md

@@ -0,0 +1,198 @@
+# Batch Processing Strategy
+
+## 核心原则
+
+**大范围 code review 必须分批处理，避免上下文溢出导致遗漏。**
+
+---
+
+## 分批阈值
+
+| 指标 | 阈值 | 处理方式 |
+|------|------|----------|
+| 文件数 | ≤ 5 | 单批处理 |
+| 文件数 | 6-15 | 分 2-3 批 |
+| 文件数 | > 15 | 分 4+ 批 |
+| 单文件行数 | ≤ 200 | 正常处理 |
+| 单文件行数 | 201-500 | 重点关注 |
+| 单文件行数 | > 500 | 单独一批 |
+| 总变更行数 | ≤ 400 | 单批处理 |
+| 总变更行数 | > 400 | 必须分批 |
+
+---
+
+## 分批策略
+
+### Strategy 1: 按依赖关系分批
+
+```
+Batch 1: 基础层 (models, types, utils)
+    ↓
+Batch 2: 服务层 (services, repositories)
+    ↓
+Batch 3: 接口层 (controllers, routes, handlers)
+    ↓
+Batch 4: 表现层 (components, views)
+```
+
+**优点**: 按调用链顺序，便于追踪影响
+
+### Strategy 2: 按风险等级分批
+
+```
+Batch 1: 高风险 (auth, payment, data)
+    ↓
+Batch 2: 中风险 (business logic)
+    ↓
+Batch 3: 低风险 (UI, utils)
+```
+
+**优点**: 优先处理关键代码
+
+### Strategy 3: 按变更类型分批
+
+```
+Batch 1: 新增文件
+    ↓
+Batch 2: 修改文件 (核心逻辑)
+    ↓
+Batch 3: 修改文件 (配置/测试)
+    ↓
+Batch 4: 删除文件 (验证无残留引用)
+```
+
+**优点**: 同类变更一起处理
+
+---
+
+## 分批执行流程
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Phase 1: 分批规划                                           │
+│  ─────────────────────────────────────────────────────────  │
+│  1. 统计文件数和行数                                         │
+│  2. 选择分批策略                                             │
+│  3. 创建批次计划                                             │
+│  4. 记录到 Progress Tracker                                  │
+└─────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────┐
+│  Phase 2: 批次执行                                           │
+│  ─────────────────────────────────────────────────────────  │
+│  For each batch:                                            │
+│    1. 输出 "开始 Batch X/N"                                  │
+│    2. 逐文件分析 + Checkpoint                                │
+│    3. 输出 "完成 Batch X/N"                                  │
+│    4. 更新 Progress Tracker                                  │
+└─────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────┐
+│  Phase 3: 跨批次验证                                         │
+│  ─────────────────────────────────────────────────────────  │
+│  1. 检查跨批次依赖                                           │
+│  2. 验证调用链完整性                                         │
+│  3. 汇总所有发现                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 批次计划模板
+
+```markdown
+## Batch Plan
+
+### Overview
+- **Total Files**: 12
+- **Total Lines**: 1,500
+- **Strategy**: 按依赖关系分批
+- **Batches**: 3
+
+### Batch 1: 基础层 (4 files, ~400 lines)
+| # | File | Lines | Risk |
+|---|------|-------|------|
+| 1 | models/user.ts | 120 | Medium |
+| 2 | models/order.ts | 80 | Medium |
+| 3 | types/index.ts | 50 | Low |
+| 4 | utils/helpers.ts | 150 | Low |
+
+### Batch 2: 服务层 (4 files, ~600 lines)
+| # | File | Lines | Risk |
+|---|------|-------|------|
+| 5 | services/auth.ts | 200 | High |
+| 6 | services/order.ts | 180 | High |
+| 7 | services/payment.ts | 150 | High |
+| 8 | repositories/user.ts | 70 | Medium |
+
+### Batch 3: 接口层 (4 files, ~500 lines)
+| # | File | Lines | Risk |
+|---|------|-------|------|
+| 9 | routes/auth.ts | 150 | High |
+| 10 | routes/order.ts | 120 | Medium |
+| 11 | controllers/user.ts | 130 | Medium |
+| 12 | middleware/auth.ts | 100 | High |
+```
+
+---
+
+## 批次完成确认
+
+每个批次完成后，必须输出:
+
+```markdown
+## Batch X/N Complete
+
+### Summary
+- **Files Analyzed**: 4/4
+- **Issues Found**: 3 (1×P0, 1×P1, 1×P2)
+- **Checkpoints**: CP-001 ~ CP-004
+
+### Cross-Batch Dependencies
+| Symbol | Defined In | Used In Next Batch |
+|--------|------------|-------------------|
+| `User` | models/user.ts | services/auth.ts |
+| `validateToken()` | utils/helpers.ts | middleware/auth.ts |
+
+### Ready for Next Batch: ✅
+```
+
+---
+
+## 上下文恢复机制
+
+如果 review 中断，可以从 Progress Tracker 恢复:
+
+```markdown
+## Resume Point
+
+**Last Completed**:
+- Batch: 2/3
+- File: services/payment.ts
+- Checkpoint: CP-007
+
+**Pending**:
+- Batch 3: 4 files
+- Files: routes/auth.ts, routes/order.ts, controllers/user.ts, middleware/auth.ts
+
+**Resume Command**:
+继续从 Batch 3 开始，先读取 CP-001 ~ CP-007 的发现摘要
+```
+
+---
+
+## 与 Progress Tracker 集成
+
+在 Progress Tracker 中添加批次信息:
+
+```markdown
+## Batch Progress
+
+| Batch | Files | Status | Issues |
+|-------|-------|--------|--------|
+| 1/3 | 4 | ✅ Done | 1 |
+| 2/3 | 4 | ✅ Done | 2 |
+| 3/3 | 4 | 🔄 In Progress | - |
+
+**Current**: Batch 3, File 2/4 (routes/order.ts)
+```

package/.claude/skills/code-review/references/call-chain-analysis-protocol.md

@@ -0,0 +1,166 @@
+# Call Chain Analysis Protocol
+
+## 核心原则
+
+**深度追踪调用链，确保不遗漏间接影响的 bug。**
+
+---
+
+## 调用链分析层级
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Level 0: 当前文件内的调用                                   │
+│  ─────────────────────────────────────────────────────────  │
+│  函数 A → 函数 B → 函数 C (同一文件内)                       │
+└─────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────┐
+│  Level 1: 直接依赖 (import/require)                          │
+│  ─────────────────────────────────────────────────────────  │
+│  当前文件 → 直接导入的模块                                   │
+└─────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────┐
+│  Level 2: 间接依赖 (依赖的依赖)                              │
+│  ─────────────────────────────────────────────────────────  │
+│  当前文件 → 模块 A → 模块 B                                  │
+└─────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────┐
+│  Level 3: 反向依赖 (谁调用了我)                              │
+│  ─────────────────────────────────────────────────────────  │
+│  调用者 A → 当前文件                                         │
+│  调用者 B → 当前文件                                         │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 分析深度规则
+
+| 变更类型 | 分析深度 | 原因 |
+|----------|----------|------|
+| 函数签名变更 | Level 3 (所有调用者) | 可能破坏调用方 |
+| 返回值类型变更 | Level 3 (所有调用者) | 可能导致类型错误 |
+| 内部逻辑变更 | Level 1 (直接依赖) | 影响范围有限 |
+| 新增函数 | Level 0 (当前文件) | 无现有调用者 |
+| 删除函数 | Level 3 (所有调用者) | 必须确认无残留调用 |
+| 修改公共类型 | Level 2+ (递归追踪) | 影响范围广 |
+
+---
+
+## 使用 MCP 工具分析调用链
+
+### 使用 serena 工具
+
+```
+1. 查找符号定义:
+   mcp__serena__find_symbol(name_path="functionName", include_body=true)
+
+2. 查找引用:
+   mcp__serena__find_referencing_symbols(name_path="functionName", relative_path="src/file.ts")
+
+3. 获取文件概览:
+   mcp__serena__get_symbols_overview(relative_path="src/file.ts", depth=1)
+```
+
+### 分析流程
+
+```
+Step 1: 识别变更的符号
+    ↓
+Step 2: 使用 find_referencing_symbols 查找调用者
+    ↓
+Step 3: 对每个调用者，递归查找其调用者
+    ↓
+Step 4: 直到达到入口点 (API/UI/Job) 或无更多调用者
+    ↓
+Step 5: 记录完整调用链到 Progress Tracker
+```
+
+---
+
+## 调用链记录格式
+
+```markdown
+## Call Chain Analysis
+
+### Symbol: `validateUser()`
+
+**Definition**: src/services/auth.ts:45
+
+**Call Chain (Depth 3)**:
+```
+validateUser() [src/services/auth.ts:45]
+├── login() [src/controllers/auth.ts:20]
+│   ├── POST /api/login [src/routes/auth.ts:15]
+│   └── LoginForm.onSubmit() [src/components/LoginForm.tsx:30]
+├── register() [src/controllers/auth.ts:50]
+│   └── POST /api/register [src/routes/auth.ts:25]
+└── refreshToken() [src/services/auth.ts:80]
+    └── GET /api/refresh [src/routes/auth.ts:35]
+```
+
+**Impact Analysis**:
+- 入口点: 3 个 API 端点, 1 个 UI 组件
+- 影响范围: 认证流程全部受影响
+- 风险等级: HIGH
+```
+
+---
+
+## 关键符号识别
+
+### 高风险符号类型
+
+| 类型 | 示例 | 分析深度 |
+|------|------|----------|
+| 认证/授权 | `validateToken`, `checkPermission` | Level 3 |
+| 数据访问 | `findUser`, `saveOrder` | Level 2 |
+| 业务逻辑 | `calculatePrice`, `processPayment` | Level 2 |
+| 工具函数 | `formatDate`, `parseJSON` | Level 1 |
+| 类型定义 | `User`, `Order` | Level 2 |
+
+### 自动识别规则
+
+```
+如果符号名包含以下关键词，自动提升分析深度:
+- auth, login, token, permission → Level 3
+- save, update, delete, create → Level 2
+- validate, check, verify → Level 2
+- payment, order, transaction → Level 3
+```
+
+---
+
+## 与 Checkpoint 集成
+
+在 Checkpoint 中记录调用链分析:
+
+```markdown
+### [CP-001] src/services/auth.ts
+
+**Call Chain Analysis**:
+| Symbol | Callers | Depth | Risk |
+|--------|---------|-------|------|
+| validateUser() | 4 | 3 | HIGH |
+| hashPassword() | 2 | 2 | MEDIUM |
+| generateToken() | 3 | 2 | HIGH |
+
+**Cross-File Impact**:
+- auth.ts 变更影响 5 个文件
+- 需要检查: controllers/auth.ts, routes/auth.ts, components/LoginForm.tsx
+```
+
+---
+
+## 终止条件
+
+调用链追踪在以下情况停止:
+
+1. **到达入口点**: API 路由、UI 事件处理、定时任务
+2. **到达外部边界**: 第三方库、系统 API
+3. **循环检测**: 发现循环依赖
+4. **深度限制**: 超过 5 层（可配置）
+5. **无更多调用者**: 符号未被任何代码引用

package/.claude/skills/code-review/references/common-patterns.md

@@ -0,0 +1,321 @@
+# Common Patterns & Anti-Patterns
+
+Frequently identified issues and their solutions during code review.
+
+## JavaScript/TypeScript
+
+### Async/Await Issues
+
+```typescript
+// 🚫 Anti-Pattern: Sequential when parallel possible
+const user = await getUser(id);
+const posts = await getPosts(id);
+const comments = await getComments(id);
+
+// ✅ Pattern: Parallel execution
+const [user, posts, comments] = await Promise.all([
+  getUser(id),
+  getPosts(id),
+  getComments(id)
+]);
+```
+
+```typescript
+// 🚫 Anti-Pattern: Unhandled promise rejection
+async function load() {
+  const data = await fetch(url);  // Unhandled rejection
+}
+load();
+
+// ✅ Pattern: Proper error handling
+async function load() {
+  try {
+    const data = await fetch(url);
+  } catch (error) {
+    handleError(error);
+  }
+}
+```
+
+```typescript
+// 🚫 Anti-Pattern: await in loop
+for (const id of ids) {
+  const result = await fetch(id);  // Sequential, slow
+}
+
+// ✅ Pattern: Promise.all for parallel
+const results = await Promise.all(ids.map(id => fetch(id)));
+
+// ✅ Pattern: For rate limiting, use p-limit
+import pLimit from 'p-limit';
+const limit = pLimit(5);
+const results = await Promise.all(ids.map(id => limit(() => fetch(id))));
+```
+
+### Type Safety
+
+```typescript
+// 🚫 Anti-Pattern: Type assertion without validation
+const user = data as User;
+
+// ✅ Pattern: Runtime validation
+import { z } from 'zod';
+const UserSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+});
+const user = UserSchema.parse(data);
+```
+
+```typescript
+// 🚫 Anti-Pattern: any type
+function process(data: any) { }
+
+// ✅ Pattern: Proper typing
+function process<T extends BaseData>(data: T): ProcessedData<T> { }
+```
+
+### Null Safety
+
+```typescript
+// 🚫 Anti-Pattern: Truthy check for 0 or ''
+if (value) { }  // Fails for 0, '', false
+
+// ✅ Pattern: Explicit null check
+if (value != null) { }
+if (value !== undefined) { }
+```
+
+```typescript
+// 🚫 Anti-Pattern: Optional chaining without fallback
+const name = user?.profile?.name;  // Could be undefined
+
+// ✅ Pattern: Nullish coalescing
+const name = user?.profile?.name ?? 'Anonymous';
+```
+
+## React
+
+### State Management
+
+```typescript
+// 🚫 Anti-Pattern: Derived state in useState
+const [fullName, setFullName] = useState(`${firstName} ${lastName}`);
+
+// ✅ Pattern: Compute derived values
+const fullName = useMemo(() => `${firstName} ${lastName}`, [firstName, lastName]);
+```
+
+```typescript
+// 🚫 Anti-Pattern: Stale closure
+useEffect(() => {
+  const interval = setInterval(() => {
+    setCount(count + 1);  // Always uses initial count
+  }, 1000);
+}, []);
+
+// ✅ Pattern: Functional update
+useEffect(() => {
+  const interval = setInterval(() => {
+    setCount(c => c + 1);  // Uses current value
+  }, 1000);
+  return () => clearInterval(interval);
+}, []);
+```
+
+### Performance
+
+```typescript
+// 🚫 Anti-Pattern: Inline handlers creating new references
+<Button onClick={() => handleClick(id)} />
+
+// ✅ Pattern: Stable reference with useCallback
+const handleButtonClick = useCallback(() => handleClick(id), [id]);
+<Button onClick={handleButtonClick} />
+```
+
+```typescript
+// 🚫 Anti-Pattern: Missing key or using index
+{items.map((item, index) => <Item key={index} />)}
+
+// ✅ Pattern: Stable unique key
+{items.map(item => <Item key={item.id} />)}
+```
+
+### Component Design
+
+```typescript
+// 🚫 Anti-Pattern: Prop drilling
+<GrandParent>
+  <Parent data={data}>
+    <Child data={data}>
+      <GrandChild data={data} />  // Only one that uses it
+    </Child>
+  </Parent>
+</GrandParent>
+
+// ✅ Pattern: Context or composition
+const DataContext = createContext();
+<DataContext.Provider value={data}>
+  <GrandParent>
+    <Parent>
+      <Child>
+        <GrandChild />  // Uses useContext
+      </Child>
+    </Parent>
+  </GrandParent>
+</DataContext.Provider>
+```
+
+## Database/SQL
+
+### Query Optimization
+
+```sql
+-- 🚫 Anti-Pattern: SELECT *
+SELECT * FROM users WHERE id = 1;
+
+-- ✅ Pattern: Select only needed columns
+SELECT id, name, email FROM users WHERE id = 1;
+```
+
+```sql
+-- 🚫 Anti-Pattern: No index on WHERE clause
+SELECT * FROM orders WHERE created_at > '2024-01-01';
+
+-- ✅ Pattern: Add appropriate index
+CREATE INDEX idx_orders_created_at ON orders(created_at);
+```
+
+```sql
+-- 🚫 Anti-Pattern: OR on different columns
+SELECT * FROM users WHERE email = 'x' OR phone = 'y';
+
+-- ✅ Pattern: UNION for different indexes
+SELECT * FROM users WHERE email = 'x'
+UNION
+SELECT * FROM users WHERE phone = 'y';
+```
+
+### Transaction Safety
+
+```typescript
+// 🚫 Anti-Pattern: No transaction for related operations
+await db.users.update(userId, { balance: newBalance });
+await db.transactions.create({ userId, amount });  // What if this fails?
+
+// ✅ Pattern: Use transaction
+await db.transaction(async (tx) => {
+  await tx.users.update(userId, { balance: newBalance });
+  await tx.transactions.create({ userId, amount });
+});
+```
+
+## API Design
+
+### Error Handling
+
+```typescript
+// 🚫 Anti-Pattern: Generic error response
+res.status(500).json({ error: 'Something went wrong' });
+
+// ✅ Pattern: Structured error response
+res.status(400).json({
+  code: 'VALIDATION_ERROR',
+  message: 'Invalid input',
+  details: [
+    { field: 'email', error: 'Invalid email format' }
+  ]
+});
+```
+
+### Input Validation
+
+```typescript
+// 🚫 Anti-Pattern: No validation
+app.post('/users', (req, res) => {
+  db.users.create(req.body);  // Trust user input
+});
+
+// ✅ Pattern: Validate and sanitize
+app.post('/users', async (req, res) => {
+  const validated = UserCreateSchema.parse(req.body);
+  const sanitized = sanitize(validated);
+  await db.users.create(sanitized);
+});
+```
+
+## Testing
+
+### Test Quality
+
+```typescript
+// 🚫 Anti-Pattern: Testing implementation details
+expect(component.state.isLoading).toBe(true);
+
+// ✅ Pattern: Test behavior/output
+expect(screen.getByRole('progressbar')).toBeInTheDocument();
+```
+
+```typescript
+// 🚫 Anti-Pattern: Brittle snapshot
+expect(component).toMatchSnapshot();  // Breaks on any change
+
+// ✅ Pattern: Specific assertions
+expect(screen.getByText('Welcome')).toBeInTheDocument();
+expect(screen.getByRole('button', { name: 'Submit' })).toBeEnabled();
+```
+
+### Mock Patterns
+
+```typescript
+// 🚫 Anti-Pattern: Over-mocking
+jest.mock('./database');
+jest.mock('./cache');
+jest.mock('./logger');
+jest.mock('./utils');
+// Test is now meaningless
+
+// ✅ Pattern: Minimal mocking
+jest.mock('./externalApi');  // Only mock external dependencies
+// Let internal modules work naturally
+```
+
+## Security Patterns
+
+### Authentication
+
+```typescript
+// 🚫 Anti-Pattern: Password in URL
+GET /login?password=secret
+
+// ✅ Pattern: POST with body
+POST /login
+{ "password": "secret" }  // Over HTTPS
+```
+
+```typescript
+// 🚫 Anti-Pattern: Predictable session ID
+const sessionId = `user-${userId}`;
+
+// ✅ Pattern: Cryptographic randomness
+const sessionId = crypto.randomBytes(32).toString('hex');
+```
+
+### Data Exposure
+
+```typescript
+// 🚫 Anti-Pattern: Return entire user object
+res.json(user);  // Includes passwordHash
+
+// ✅ Pattern: Explicit field selection
+res.json({
+  id: user.id,
+  name: user.name,
+  email: user.email
+});
+
+// Or use a DTO
+res.json(UserDTO.fromEntity(user));
+```
+