@tinkcarlos/skillora 0.2.0

package/.claude/skills/bug-fixing/references/investigation-checklist.md

@@ -0,0 +1,263 @@
+# Investigation Checklist
+
+Use this checklist to ensure thorough bug investigation.
+
+## File Discovery
+
+- [ ] **Code files** — Source code in bug area
+- [ ] **Database schema** — `*.sql`, migration files
+- [ ] **ORM models** — Model/entity definitions
+- [ ] **API schemas** — Request/response definitions
+- [ ] **Config files** — `.env*`, `*.yaml`, `*.json`, `*.xml`, `*.toml`, `*.ini`
+- [ ] **Infrastructure** — Dockerfile, docker-compose, K8s manifests
+- [ ] **CI/CD** — Pipeline definitions
+- [ ] **Tests** — Related test files
+
+## Direct Impact Scoping (Modules / Surfaces)
+
+Before searching code, write down what is directly impacted (1–5 items):
+
+- [ ] **UI surfaces**: route/page + control name + expected outcome
+- [ ] **API surfaces**: method + endpoint + expected response
+- [ ] **Background surfaces**: job/task name + expected artifact/output
+
+This prevents “same error, different entry point” confusion and makes the scope precise.
+
+## Data Flow Tracing
+
+**CRITICAL**: Trace the FULL path from external source to final display. Missing any layer can cause multi-fix loops.
+
+```
+External Data Source (file upload, CSV/JSON import, user input, third-party API)
+    ↓
+Parser/Importer (format conversion, normalization, validation)
+    ↓
+User Action (trigger processing)
+    ↓
+Frontend (Component → State → API call)
+    ↓
+Network (Request body, headers)
+    ↓
+Backend (Route → Service → Repository)
+    ↓
+Database (Query → Schema → Data)
+    ↓
+Response (Status → Body → Headers)
+    ↓
+Frontend (Parse → Update State → Render)
+```
+
+**File Import/Upload Specific Checks:**
+
+- [ ] **Parser code**: How are column names/keys normalized? Are special characters handled?
+- [ ] **Data transformation**: How are types converted? What happens to edge cases?
+- [ ] **Data storage**: What exactly is stored? Original or transformed data?
+- [ ] **Data display**: What is shown to user? Is it the stored value or re-transformed?
+
+## Environment Check
+
+- [ ] Environment variables loaded correctly?
+- [ ] Database connection working?
+- [ ] External API keys valid?
+- [ ] Feature flags enabled?
+
+## Phase 0: Clarify & Triage (Noise vs Failure)
+
+Goal: classify in **1–2 question rounds** so you don’t fix the wrong thing.
+
+Rules:
+- Ask **1–2 questions per round** (max).
+- Prefer **multiple-choice** with an “Other/Not sure” option.
+- Don’t ask the user to confirm your assumptions — **write assumptions** and proceed.
+
+### High-signal questions (pick 1–2)
+
+- **Final outcome?**
+  - (A) Fails (no expected output)
+  - (B) Succeeds but console is noisy (errors/warnings)
+  - (C) Succeeds but result/data is wrong
+- **Entry point?** (UI route/button, API endpoint, background job)
+- **Evidence?** Ask for the smallest artifact that proves it:
+  - screenshot/video
+  - console log (first error + stack)
+  - network trace (request + response)
+- **Multiple entry points?** “Does the same log happen in more than one place? If yes, list up to 3.”
+- **Noise handling intent?**
+  - (A) Reduce false alarms (log level / avoid optional code paths)
+  - (B) Fix root compatibility (only if user impact exists)
+  - (C) Not sure (default: reduce noise unless impact is proven)
+
+### Noise vs Failure quick rules
+
+- **Failure**: user blocked, wrong output/data, security/privacy impact.
+- **Noise**: flow succeeds; errors are recoverable/optional (compat gaps, CSP blocks, optional resource failures).
+
+## Search & Discovery (IDE first, `rg` fallback)
+
+Prefer IDE file search/content search (scope by folder + file pattern). If using CLI, keep scope narrow first.
+
+```bash
+# File discovery (no pipes)
+rg --files --glob "*.sql"
+rg --files --glob ".env*"
+rg --files --glob "*.{yaml,yml,json,xml,toml,ini}"
+rg --files --glob "**/{migrations,alembic}/**"
+rg --files --glob "*.{ts,tsx,js,jsx,py,go,java,kt,cs}"
+
+# Content search (narrow first, then expand)
+rg -n "error message here" path/to/suspected/area/
+rg -n "error message here" . --glob "*.{ts,tsx,js,jsx,py,go,java}"
+```
+
+## Symbol & Reference Discovery (Functions / Classes / Queries)
+
+When you identify a likely bug location, enumerate the code entities involved and where they are used.
+
+- [ ] **Key entities**: functions, classes, methods, queries, stored procedures, config keys
+- [ ] **Direct references**: find where the entity is called/queried/imported
+- [ ] **Key indirect references**: find callers of the direct callers (Layer 2)
+
+Preferred approach:
+
+- IDE “Find References” / “Go to Definition” (fastest and most precise)
+- CLI fallback:
+  - `rg -n "<symbolName>" . --glob "*.{ts,tsx,js,jsx,py,go,java,sql}"`
+
+For SQL/db issues, also search by:
+
+- table name / column name
+- migration revision identifiers
+- ORM model name
+
+### Recent changes
+
+```bash
+git log --oneline -20
+git diff HEAD~5
+```
+
+## Replay Exercises (Skill QA)
+
+Use these to verify the workflow can classify and plan in **1–2 rounds**.
+
+### 1) Functional failure (P0)
+
+Bug report:
+- “Clicking Export ZIP does nothing. No file downloads.”
+
+Round-1 questions (pick 1–2):
+- Final outcome? (A/B/C)
+- Which entry point? (UI route/button)
+
+Expected classification:
+- **Failure (P0)** — user is blocked.
+
+Expected next plan:
+- Reproduce + capture evidence → RCA → impact analysis → minimal fix → matrix verification.
+
+### 2) Success but console noise (P2) — e.g. CSP blocks / unsupported features
+
+Bug report:
+- “ZIP downloads successfully, but console shows red CSP errors and a compatibility warning.”
+
+Round-1 questions (pick 1–2):
+- Final outcome? (A/B/C)
+- Is there any user-visible impact or wrong output/data? (A yes / B no)
+
+Expected classification:
+- **Noise (P2)** by default (unless impact is proven).
+
+Expected next plan:
+- Identify source of noise → add feature-detection/fallback or reduce logs → ensure no regression.
+
+### 3) Same log from multiple entry points
+
+Bug report:
+- “We see the same ‘Unauthorized’ error in the console in multiple places.”
+
+Round-1 questions (pick 1–2):
+- Which entry points show it? List up to 3.
+- Do ALL of them actually fail, or are some success-but-noisy?
+
+Expected classification:
+- Mixed until disambiguated (often **multiple code paths**).
+
+Expected next plan:
+- Split by entry point → reproduce each → prioritize true failures → fix root cause per path.
+
+## Root Cause Statement Template
+
+```markdown
+**Root Cause**: The bug occurs because [specific code/config]
+does [actual behavior] instead of [expected behavior]
+when [specific condition].
+
+**Evidence**: [File:Line] shows [code snippet]
+```
+
+---
+
+## 🔴 Structured Logging Checklist (结构化日志检查)
+
+**有效的日志是快速定位 Bug 的关键！**
+
+> 研究表明：具有良好日志系统的团队解决生产问题速度快 40% (Gartner)
+
+### 日志级别使用规范
+
+| 级别 | 用途 | 示例 |
+|------|------|------|
+| **ERROR** | 需要立即处理的错误 | 数据库连接失败、支付失败 |
+| **WARN** | 潜在问题，但不影响主流程 | 重试成功、降级触发 |
+| **INFO** | 关键业务事件 | 用户登录、订单创建 |
+| **DEBUG** | 开发调试信息 | 函数入参、中间状态 |
+
+### 日志内容检查清单
+
+- [ ] **上下文完整** - 包含 user_id, request_id, timestamp
+- [ ] **可搜索** - 使用结构化格式 (JSON)
+- [ ] **敏感信息脱敏** - 密码、token、PII 已处理
+- [ ] **错误信息完整** - 包含 stack trace
+
+### 日志格式示例
+
+```json
+// ✅ 好的日志
+{
+  "timestamp": "2025-01-19T10:30:00Z",
+  "level": "ERROR",
+  "message": "Payment failed",
+  "context": {
+    "user_id": "u123",
+    "request_id": "req-abc",
+    "order_id": "ord-456",
+    "error_code": "INSUFFICIENT_FUNDS"
+  },
+  "stack_trace": "..."
+}
+
+// ❌ 差的日志
+console.log("Error occurred")
+```
+
+### 调试时添加日志的位置
+
+| 位置 | 记录内容 |
+|------|----------|
+| **函数入口** | 关键参数值 |
+| **分支点** | 走了哪个分支、为什么 |
+| **外部调用前后** | 请求/响应内容 |
+| **异常捕获** | 完整错误信息 + 上下文 |
+| **状态变更** | 变更前后的值 |
+
+### 日志工具推荐
+
+| 场景 | 工具 |
+|------|------|
+| 前端错误追踪 | Sentry |
+| 后端日志聚合 | ELK Stack (Elasticsearch + Logstash + Kibana) |
+| Node.js | Winston, Pino |
+| Python | structlog, loguru |
+| Java | Log4j2, SLF4J |
+
+