@tinkcarlos/skillora 0.2.0

package/.claude/skills/bug-fixing/references/rca-guide.md

@@ -0,0 +1,428 @@
+# Root Cause Analysis Guide
+
+> RCA techniques to identify true bug sources, not symptoms.
+
+## Table of Contents
+
+- [RCA Principles](#rca-principles)
+- [RCA Techniques](#rca-techniques)
+  - [Five Whys](#1-five-whys)
+  - [Fishbone Diagram (Ishikawa)](#2-fishbone-diagram-ishikawa)
+  - [Timeline Analysis](#3-timeline-analysis)
+  - [Fault Tree Analysis](#4-fault-tree-analysis)
+  - [Change Analysis](#5-change-analysis)
+  - [Git Bisect](#6-git-bisect-binary-search-debugging)
+- [Code Path Tracing](#code-path-tracing)
+- [Root Cause Categories](#root-cause-categories)
+- [RCA Report Template](#rca-report-template)
+
+Techniques for identifying the true source of bugs, not just symptoms.
+
+---
+
+## RCA Principles
+
+1. **Don't fix symptoms** - A fix that addresses symptoms will see the bug return
+2. **Ask "Why?" repeatedly** - Keep digging until you find the fundamental cause
+3. **Verify the cause** - Prove the root cause by showing the fix prevents the bug
+4. **Look for patterns** - Similar bugs may have the same root cause
+5. **Document for learning** - RCA helps prevent future similar bugs
+
+---
+
+## RCA Techniques
+
+### 1. Five Whys
+
+Start with the problem and ask "Why?" five times:
+
+```markdown
+**Problem**: Users receive duplicate emails
+
+**Why 1**: Why do users receive duplicate emails?
+→ Because the email service is called twice.
+
+**Why 2**: Why is the email service called twice?
+→ Because the submit handler fires twice.
+
+**Why 3**: Why does the submit handler fire twice?
+→ Because the button click event bubbles and triggers twice.
+
+**Why 4**: Why does the event bubble and trigger twice?
+→ Because there's no event.stopPropagation() or debouncing.
+
+**Why 5**: Why is there no prevention for double submission?
+→ Because the form component was written without considering rapid clicks.
+
+**Root Cause**: Form component lacks double-submission prevention.
+```
+
+### 2. Fishbone Diagram (Ishikawa)
+
+Categorize potential causes:
+
+```
+                    ┌─── People ──────┐
+                    │ - Training gap   │
+                    │ - Human error    │
+                    │                  │
+┌─── Process ──────┐│                  │┌─── Technology ────┐
+│ - Missing step   ││                  ││ - System bug       │
+│ - Wrong order    ││                  ││ - Integration issue│
+│ - No validation  ││      [BUG]       ││ - Performance      │
+└──────────────────┘│                  │└────────────────────┘
+                    │                  │
+┌─── Environment ──┐│                  │┌─── Data ────────────┐
+│ - Config diff    ││                  ││ - Invalid input      │
+│ - Network issue  ││                  ││ - Corrupted data     │
+│ - Resource limit │└──────────────────┘│ - Missing data       │
+└──────────────────┘                    └──────────────────────┘
+```
+
+### 3. Timeline Analysis
+
+For intermittent or timing-related bugs:
+
+```markdown
+## Timeline Analysis
+
+| Time | Event | System State | Notes |
+|------|-------|--------------|-------|
+| 00:00 | User clicks Submit | Form data valid | |
+| 00:01 | API call initiated | Loading state | |
+| 00:02 | User clicks Submit again | Already loading | No prevention! |
+| 00:03 | First API call completes | Success | |
+| 00:04 | Second API call completes | Duplicate! | |
+
+**Root Cause**: No loading state check before submit
+```
+
+### 4. Fault Tree Analysis
+
+Work backwards from the failure:
+
+```
+                    [Duplicate Email]
+                           │
+              ┌────────────┴────────────┐
+              │                         │
+    [Email sent twice]         [Two records created]
+              │                         │
+    ┌─────────┴─────────┐              │
+    │                   │              │
+[Double API call]  [Retry logic]  [Race condition]
+    │
+    │
+[No debounce on button]  ← ROOT CAUSE
+```
+
+### 5. Change Analysis
+
+Compare working vs broken states:
+
+```markdown
+## Change Analysis
+
+| Aspect | Working State | Broken State | Changed? |
+|--------|---------------|--------------|----------|
+| Code version | v1.2.3 | v1.2.4 | Yes ✓ |
+| Config | prod.yaml | prod.yaml | No |
+| Database | schema v42 | schema v42 | No |
+| Dependencies | package.json | package.json | No |
+| Environment | AWS us-east-1 | AWS us-east-1 | No |
+
+**Focus Investigation On**: Code changes in v1.2.4
+
+**Changed Files**:
+- src/services/email.ts (modified)
+- src/components/Form.tsx (modified) ← likely culprit
+
+**Root Cause**: Form.tsx change removed debounce logic
+```
+
+### 6. Git Bisect (Binary Search Debugging)
+
+**Best for**: Regression bugs where you know "it worked before"
+
+When a recent change broke functionality, use binary search to find the culprit commit:
+
+```bash
+# Start bisect session
+git bisect start
+
+# Mark current commit as broken
+git bisect bad HEAD
+
+# Mark last known working version
+git bisect good v1.2.3   # or commit hash
+
+# Git checks out middle commit - test it manually
+# Then mark result:
+git bisect good   # if this commit works
+git bisect bad    # if this commit is broken
+
+# Repeat until Git identifies the first bad commit
+# Output: "abc1234 is the first bad commit"
+
+# End session and return to original state
+git bisect reset
+```
+
+**Automated Bisect** (with test script):
+
+```bash
+# Run test automatically on each commit
+git bisect start HEAD v1.2.3
+git bisect run npm test   # or any command that exits 0=good, 1=bad
+```
+
+**When to Use Git Bisect**:
+
+| Scenario | Use Bisect? |
+|----------|-------------|
+| "It worked last week" | ✅ Yes |
+| "It never worked" | ❌ No |
+| Many commits between good/bad | ✅ Yes (efficient) |
+| Only 2-3 commits | ❌ No (just check manually) |
+| Can't reproduce reliably | ❌ No (need consistent test) |
+
+---
+
+## Code Path Tracing
+
+### Step 1: Identify Entry Point
+
+Where does the bug start?
+
+```typescript
+// Error message: "Cannot read property 'name' of undefined"
+// Stack trace points to:
+src/components/UserProfile.tsx:23
+  const name = user.name; // Error here
+```
+
+### Step 2: Trace Data Flow
+
+Follow the data from source to error:
+
+```
+Entry: UserProfile.tsx:23 (user.name)
+   ↑
+   │ user comes from props
+   │
+Source: UserProfilePage.tsx:15
+   ↑
+   │ user comes from useUser hook
+   │
+Source: hooks/useUser.ts:8
+   ↑
+   │ user comes from API response
+   │
+Source: api/users.ts:12
+   ↑
+   │ API returns null when user not found
+   │
+ROOT CAUSE: No handling for API returning null
+```
+
+### Step 3: Document the Path
+
+```markdown
+## Code Path
+
+### Execution Flow
+```
+1. UserProfilePage renders
+   └── Calls useUser(userId)
+       └── Fetches from /api/users/{id}
+           └── API returns null (user deleted)
+               └── useUser returns null
+                   └── UserProfile receives user=null
+                       └── Accesses user.name
+                           └── TypeError!
+```
+
+### Missing Checks
+| Location | Should Check | Current |
+|----------|-------------|---------|
+| API response | user exists | No ❌ |
+| useUser hook | null handling | No ❌ |
+| UserProfile | user prop | No ❌ |
+
+### Fix Location Options
+1. API: Return 404 (proper REST) ← Best
+2. Hook: Return loading/error state
+3. Component: Null check before render
+
+---
+
+## Root Cause Categories
+
+### Logic Errors
+
+```typescript
+// Bug: Off-by-one error
+for (let i = 0; i <= array.length; i++) { // <= should be <
+  process(array[i]); // undefined on last iteration
+}
+
+// Bug: Wrong operator
+if (user.role = 'admin') { // = should be ===
+  // Always true, assigns 'admin' to role
+}
+
+// Bug: Incorrect condition
+if (items.length > 0 || items.length < 10) { // || should be &&
+  // Always true if length > 0
+}
+```
+
+### Async/Timing Errors
+
+```typescript
+// Bug: Race condition
+let data;
+async function loadData() {
+  data = await fetchData();
+}
+loadData();
+console.log(data); // undefined - loadData hasn't finished
+
+// Bug: Stale closure
+useEffect(() => {
+  const interval = setInterval(() => {
+    setCount(count + 1); // count is stale
+  }, 1000);
+}, []); // missing count dependency
+
+// Bug: Unhandled promise rejection
+async function save() {
+  await api.save(data); // No try/catch
+}
+```
+
+### State Errors
+
+```typescript
+// Bug: Mutation of state
+const [items, setItems] = useState([]);
+function addItem(item) {
+  items.push(item); // Mutates state directly!
+  setItems(items);  // Same reference, no re-render
+}
+
+// Bug: Invalid state transition
+if (status === 'pending') {
+  setStatus('complete');
+} else if (status === 'processing') {
+  setStatus('complete'); // Can go from processing to complete?
+}
+```
+
+### Data Errors
+
+```typescript
+// Bug: Unexpected data type
+function formatDate(date) {
+  return date.toISOString(); // Fails if date is string
+}
+
+// Bug: Missing data validation
+function createUser(data) {
+  return { email: data.email.toLowerCase() }; // Fails if email undefined
+}
+
+// Bug: Data shape assumption
+function getFirstItem(response) {
+  return response.data.items[0].name; // Many assumptions!
+}
+```
+
+### Integration Errors
+
+```typescript
+// Bug: API contract mismatch
+// Frontend expects: { user: { name: string } }
+// Backend returns: { data: { user: { name: string } } }
+const name = response.user.name; // undefined
+
+// Bug: Version mismatch
+// Library v1: axios.get().then(res => res.data)
+// Library v2: axios.get().then(res => res.body)
+
+// Bug: Environment difference
+const apiUrl = process.env.API_URL; // undefined in production
+```
+
+---
+
+## RCA Report Template
+
+```markdown
+# Root Cause Analysis Report
+
+## Bug Summary
+| Field | Value |
+|-------|-------|
+| Bug ID | BUG-XXX |
+| Summary | [One line] |
+| Severity | Critical / High / Medium / Low |
+| Date Found | [Date] |
+| Date Fixed | [Date] |
+
+## Problem Statement
+[Detailed description of the bug]
+
+## Impact
+- Users affected: [Number/scope]
+- Features affected: [List]
+- Duration: [How long issue existed]
+
+## Root Cause
+
+### 5 Whys Analysis
+[Complete 5 whys]
+
+### Root Cause Statement
+**Category**: [Logic/Async/State/Data/Integration]
+
+**Description**: [Clear statement of root cause]
+
+**Code Location**: 
+- File: [path]
+- Line: [number]
+- Function: [name]
+
+## Fix
+
+### Solution
+[Description of fix]
+
+### Code Changes
+[Diff or description]
+
+### Why This Fix?
+[Justification]
+
+## Verification
+- [ ] Bug cannot be reproduced
+- [ ] Tests added for bug case
+- [ ] Related features verified
+
+## Prevention
+
+### Immediate Actions
+- [Action 1]
+- [Action 2]
+
+### Long-term Improvements
+- [Improvement 1]
+- [Improvement 2]
+
+## Lessons Learned
+- [Lesson 1]
+- [Lesson 2]
+
+## Related Bugs
+- [BUG-XXX] - Similar issue in [component]
+```

package/.claude/skills/bug-fixing/references/similar-bug-patterns.md

@@ -0,0 +1,113 @@
+# Similar Bug Patterns & Search Strategies
+
+修复一个 bug 后，使用本指南搜索整个项目中的相似问题。
+
+## 核心方法
+
+```
+1. 提取模式 → 2. 构建搜索 → 3. 全项目扫描 → 4. 逐一验证 → 5. 批量修复
+```
+
+## 常见 Bug 模式
+
+### 1. 硬编码数据 (Hardcoded Data)
+
+**特征**: 使用静态值而非从配置/API获取
+
+**搜索策略**:
+- 搜索相同的硬编码值
+- 搜索 `INITIAL_*`, `DEFAULT_*`, `MOCK_*` 常量
+- 搜索初始化为非空数组的状态
+
+**验证**: 该值应该从哪里获取？配置文件？API？
+
+---
+
+### 2. 占位符代码 (Placeholder Code)
+
+**特征**: 函数只有日志/注释，没有实际逻辑
+
+**搜索策略**:
+- 搜索 `// TODO`, `// FIXME`, `// 后续实现`
+- 搜索只有 `console.log` 的处理函数
+- 搜索带 `placeholder`, `stub`, `mock` 注释的代码
+
+**验证**: 函数应该做什么？实际做了吗？
+
+---
+
+### 3. 缺少集成 (Missing Integration)
+
+**特征**: 前端有操作但没调用后端，或反之
+
+**搜索策略**:
+- 列出所有 `handle*` / `on*` 函数
+- 检查哪些没有 API 调用
+- 对比前端功能与后端 API 清单
+
+**验证**: 每个用户操作都有对应的后端调用吗？
+
+---
+
+### 4. 契约不匹配 (Contract Mismatch)
+
+**特征**: 前后端字段名/结构不一致
+
+**搜索策略**:
+- 对比前端表单字段与后端 Schema
+- 搜索驼峰/下划线命名不一致
+- 检查请求体结构与 API 期望
+
+**验证**: 前端发送的字段名与后端期望的完全一致吗？
+
+---
+
+### 5. 状态不同步 (State Not Synced)
+
+**特征**: 本地状态与服务器数据脱节
+
+**搜索策略**:
+- 搜索初始化为空但无数据获取的状态
+- 搜索 CUD 操作后没有刷新列表的代码
+- 检查乐观更新是否有回滚机制
+
+**验证**: 状态从哪里来？操作后如何同步？
+
+---
+
+## 搜索执行模板
+
+```bash
+# 通用搜索模板（根据实际情况调整）
+# 建议：先缩小范围（疑似目录 + glob），再逐步扩展到全仓库（.）
+
+# 1. 搜索特定值
+rg -n "搜索词" path/to/suspected/area/ --glob "*.ext"
+
+# 2. 搜索模式
+rg -n "pattern" path/to/suspected/area/ --glob "*.{ts,tsx}"
+
+# 3. 列出文件后人工检查
+rg -l "pattern" path/to/suspected/area/ --glob "*.tsx"
+```
+
+## 报告模板
+
+```markdown
+## Similar Bug Hunt Report
+
+**原始 Bug**: [简述]
+**Bug 模式**: [硬编码/占位符/缺少集成/契约不匹配/状态不同步]
+**搜索关键词**: [实际搜索的内容]
+
+### 搜索结果
+
+| 文件 | 行号 | 问题描述 | 状态 |
+|------|------|----------|------|
+| xxx.tsx | 123 | 同样的问题 | ✅ 已修复 |
+| yyy.tsx | 45 | 误报 | ⏭️ 跳过 |
+
+### 结论
+共发现 N 处相似问题，已全部修复。
+```
+