@tinkcarlos/skillora 0.2.0

package/.claude/skills/bug-fixing/references/bug-records.md

@@ -0,0 +1,88 @@
+# Bug Records - Project-Specific Bug Documentation
+
+> **Purpose**: Record all bugs fixed in the current project with root cause and fix method only.
+> **Update Rule**: MANDATORY update after every bug fix. If previous fix was incomplete, update the record.
+
+---
+
+## Record Template
+
+```markdown
+### [BUG-XXX] Brief Description
+**Date**: YYYY-MM-DD
+**Severity**: P0/P1/P2
+
+**Root Cause**:
+[1-2 sentences explaining WHY the bug occurred]
+
+**Fix Method**:
+[Concise description of HOW the bug was fixed]
+
+**Files Modified**:
+- `path/to/file1.ts`
+- `path/to/file2.ts`
+
+**Environment Impact**:
+- [ ] Development
+- [ ] Staging
+- [ ] Production
+```
+
+---
+
+## Bug Records
+
+<!-- Add new records below this line, newest first -->
+
+### [BUG-001] Example: Environment Configuration Mismatch
+**Date**: 2024-XX-XX
+**Severity**: P1
+
+**Root Cause**:
+Bug fix only modified production `.env` file, but development mode uses `.env.development` which was not updated.
+
+**Fix Method**:
+1. Identified all environment files: `.env`, `.env.development`, `.env.production`, `.env.local`
+2. Applied the same configuration change to ALL relevant environment files
+3. Verified startup in both dev and prod modes
+
+**Files Modified**:
+- `.env`
+- `.env.development`
+- `.env.production`
+
+**Environment Impact**:
+- [x] Development
+- [ ] Staging
+- [x] Production
+
+---
+
+## Quick Reference: Common Root Causes
+
+| Category | Root Cause Pattern | Prevention |
+|----------|-------------------|------------|
+| **Environment** | Config only in one env file | Check ALL env files |
+| **Import** | Wrong import path/syntax | Verify module resolution |
+| **State** | Race condition/stale state | Add proper synchronization |
+| **Type** | Type mismatch/null check | Enable strict TypeScript |
+| **API** | Contract mismatch | Verify request/response schema |
+| **Dependency** | Version incompatibility | Lock versions, test upgrades |
+
+---
+
+## Statistics
+
+| Month | Total Bugs | P0 | P1 | P2 | Most Common Category |
+|-------|------------|----|----|----|--------------------|
+| YYYY-MM | 0 | 0 | 0 | 0 | - |
+
+---
+
+## Update Checklist
+
+After fixing a bug, ensure:
+- [ ] New record added with root cause and fix method
+- [ ] Previous incomplete fix records updated if applicable
+- [ ] Environment impact correctly marked
+- [ ] `bug-fixing-guide.md` updated if this is a new pattern

package/.claude/skills/bug-fixing/references/code-review-gate.md

@@ -0,0 +1,81 @@
+# Post-fix Code Review Gate (Bug Fixes)
+
+The goal of the code review gate is to prevent “fixed the symptom, introduced a new bug” outcomes.
+This checklist is optimized for bug-fix PRs/patches: small changes, high confidence.
+
+## When to run
+
+Run this **after** your verification steps (tests/lint/build) pass, but **before** declaring the bug “done”.
+
+If the review finds issues, update your scope/impact lists and iterate the fix loop.
+
+## Review checklist (bug-fix focused)
+
+### 1) Correctness & edge cases
+
+- Does the fix address the **root cause**, not only the symptom?
+- Are boundary cases handled? (empty inputs, missing data, nulls, timeouts, retries)
+- Are error messages actionable (for users and for operators)?
+- Is behavior deterministic where it should be (no accidental randomness)?
+
+### 2) Contract compatibility (very common regression source)
+
+- API shape: no accidental breaking changes (renamed fields, removed keys, changed types)
+- Defaults: distinguish **omitted** vs **null** vs **empty** consistently
+- Backward compatibility: legacy fallbacks do not override explicit new settings
+- Sorting/pagination/filtering: unchanged unless explicitly part of the fix
+
+### 3) Reference safety (blast radius control)
+
+- Any changed function/class is referenced elsewhere: did you update or preserve callers?
+- Any shared config/mapping affects multiple consumers: did you validate list + detail + selection surfaces?
+- Any stringly-typed identifiers (model IDs, URLs, enum values): are they validated and tested?
+
+Tip: if you changed a mapping or URL builder, add a unit test that locks the behavior.
+
+### 4) Security & privacy
+
+- No secrets in logs, errors, or diffs
+- Authorization/permissions still enforced on all paths (including new fallbacks)
+- Avoid widening network access implicitly (new external calls, proxies, open redirects)
+
+### 5) Performance & failure modes
+
+- No unnecessary N+1 behavior (queries, API calls, file reads) introduced
+- Timeouts are explicit; retries are bounded
+- Caching/invalidation remains correct (no stale reads, no cache poisoning)
+- Background tasks do not accidentally spawn unbounded work
+
+### 6) Maintainability & clarity
+
+- Minimal change: no unrelated refactor, no style-only churn
+- Names and comments clarify intent (especially around fallbacks and edge cases)
+- Configuration-driven behavior is documented where users will find it
+
+## Review output template (copy/paste)
+
+```markdown
+## Code Review Gate
+- Scope reviewed:
+- Correctness/edge cases:
+- Contract compatibility:
+- Reference safety:
+- Security/privacy:
+- Performance/failure modes:
+- Maintainability:
+- Findings:
+  - Fixed in this patch:
+  - Follow-ups (if any):
+```
+
+## Iterate rule
+
+If the review finds issues, do not “paper over” them. Update:
+
+- Scope discovery summary (what else is impacted)
+- Impact analysis (layers 0–5)
+- Verification matrix (add a regression check for the newly discovered risk)
+
+Then repeat the fix loop.
+
+

package/.claude/skills/bug-fixing/references/common-bugs.md

@@ -0,0 +1,140 @@
+# Common Bug Patterns
+
+Quick reference for frequently encountered bug types.
+
+## API/Library Changes
+
+| Symptom | Cause | Investigation |
+|---------|-------|---------------|
+| `unexpected argument` | API signature changed | Check library changelog |
+| `attribute not found` | Class/module restructured | Check import paths |
+| `deprecated warning` | API will be removed | Find replacement API |
+
+**Fix Approach**:
+1. Check library version: `pip show package` or `npm list package`
+2. Read changelog for breaking changes
+3. Update code to new API
+
+## Frontend-Backend Sync
+
+| Symptom | Cause | Investigation |
+|---------|-------|---------------|
+| UI shows success, action failed | Not reading response status | Check response handling |
+| Data not updating | Using wrong response field | Compare response schema |
+| 401/403 errors | Auth token issue | Check token storage/sending |
+
+**Fix Approach**:
+1. Check network tab in browser devtools
+2. Compare request/response with API schema
+3. Ensure frontend uses actual response fields
+
+## Database Issues
+
+| Symptom | Cause | Investigation |
+|---------|-------|---------------|
+| `column not found` | Migration not applied | Check migration status |
+| Constraint violation | Missing field/wrong type | Check ORM vs DB schema |
+| Slow queries | Missing index | Run EXPLAIN ANALYZE |
+
+**Fix Approach**:
+1. Compare ORM model with actual DB schema
+2. Create migration if needed
+3. Apply migration and verify
+
+## Configuration Issues
+
+| Symptom | Cause | Investigation |
+|---------|-------|---------------|
+| Works locally, fails in prod | Missing env var | Check .env files |
+| Feature not working | Feature flag disabled | Check config files |
+| Wrong API endpoint | Hardcoded URL | Check for env variable usage |
+
+**Fix Approach**:
+1. List all env vars: `env | grep PREFIX`
+2. Compare local vs production configs
+3. Use environment variables, not hardcoded values
+
+## State Management
+
+| Symptom | Cause | Investigation |
+|---------|-------|---------------|
+| Stale data displayed | Cache not invalidated | Check cache logic |
+| Inconsistent UI | State mutation | Check for direct state changes |
+| Race conditions | Async timing issues | Check await/async usage |
+
+**Fix Approach**:
+1. Trace state updates through data flow
+2. Ensure immutable state updates
+3. Add proper loading/error states
+
+## Integration Issues
+
+| Symptom | Cause | Investigation |
+|---------|-------|---------------|
+| Field name mismatch | Frontend/backend contract differs | Compare schemas |
+| Type mismatch | Serialization/parsing issue | Check type definitions |
+| Missing data | Optional field not handled | Check null handling |
+
+**Fix Approach**:
+1. Define shared types/schemas
+2. Generate types from API spec
+3. Add proper null checks
+
+## UI Positioning Issues (Popup/Tooltip/Menu)
+
+| Symptom | Cause | Investigation |
+|---------|-------|---------------|
+| Popup clipped at bottom | No viewport boundary check | Check if position uses raw clientY |
+| Menu hidden behind element | z-index or stacking context | Check z-index and parent overflow |
+| Tooltip cut off at edge | No flip/boundary logic | Check positioning calculation |
+| Dropdown scrolls with page | Using absolute instead of fixed | Check position strategy |
+
+**Fix Approach**:
+1. Use `getBoundingClientRect()` to get element dimensions
+2. Compare with `window.innerHeight/innerWidth`
+3. Flip direction or clamp position when near edges
+4. Use `useLayoutEffect` for position adjustments (before paint)
+
+```tsx
+// Standard boundary-aware positioning
+useLayoutEffect(() => {
+  if (!ref.current) return;
+  const rect = ref.current.getBoundingClientRect();
+  const vh = window.innerHeight;
+  const vw = window.innerWidth;
+  
+  // Flip if overflow
+  if (position.y + rect.height > vh - 10) {
+    setY(position.y - rect.height);
+  }
+  if (position.x + rect.width > vw - 10) {
+    setX(position.x - rect.width);
+  }
+}, [position]);
+```
+
+**Detection**:
+```bash
+# Find popup components without boundary check
+grep -rn "clientX\|clientY" --include="*.tsx" -B 2 -A 10 | grep -v "innerHeight\|innerWidth"
+```
+
+---
+
+## Similar Bug Search
+
+After fixing any pattern above, search for similar occurrences:
+
+```bash
+# Example: Find all hardcoded URLs
+grep -rn "http://\|https://" --include="*.ts" --include="*.py" | grep -v "env\|config"
+
+# Example: Find all direct state mutations
+grep -rn "\.push(\|\.splice(\|delete " --include="*.ts" --include="*.tsx"
+
+# Example: Find all missing await
+grep -rn "async function" --include="*.ts" -A 5 | grep -v "await"
+
+# Example: Find popup/menu without boundary detection
+grep -rn "position: fixed\|position: absolute" --include="*.tsx" | grep -i "menu\|popup\|tooltip"
+```

package/.claude/skills/bug-fixing/references/complete-workflow.md

@@ -0,0 +1,361 @@
+# Complete Bug Fixing Workflow (完整工作流程)
+
+本文档包含 bug-fixing 各阶段的详细操作指南。
+
+---
+
+## Phase -1: Knowledge Base Query (MANDATORY)
+
+**修复任何 Bug 前，必须先查询 bug-guide.md！**
+
+### 查询流程
+
+1. 读取 `references/bug-guide.md`
+2. 搜索匹配的 Bug 模式:
+   - 按症状关键词搜索
+   - 按错误类型分类查找
+   - 按技术栈筛选
+3. 如果找到匹配模式:
+   - 直接应用已知解决方案
+   - 跳过部分调查阶段 (可选)
+   - 标注：基于历史经验修复
+4. 如果未找到匹配:
+   - 标注：新 Bug 模式，需完整调查
+   - 继续标准流程
+
+### 匹配决策矩阵
+
+| 匹配度 | 定义 | 处理方式 |
+|--------|------|---------|
+| 🟢 **高匹配** | 症状、根因、技术栈都匹配 | 直接应用修复策略，可跳过 RCA |
+| 🟡 **中匹配** | 症状相似，但细节不同 | 参考策略，但需验证假设 |
+| 🔴 **无匹配** | 找不到相关模式 | 完整调查，修复后必须更新知识库 |
+
+### Phase -1 输出模板
+
+```markdown
+## 📚 Phase -1: 知识库查询结果
+
+### 搜索关键词
+- 症状: [用户描述的症状关键词]
+- 错误类型: [如: 状态不同步, API 超时, 类型错误]
+- 技术栈: [如: React, FastAPI, PostgreSQL]
+
+### 匹配结果
+| 匹配度 | 模式名称 | 相关性说明 |
+|--------|---------|-----------|
+| 🟢 高 | [Category X: Pattern Name] | 症状完全匹配 |
+
+### 决策
+- [ ] 应用已知解决方案
+- [x] 参考已知模式，执行完整流程
+- [ ] 新模式，执行完整流程 + Phase 6 知识沉淀
+```
+
+---
+
+## Phase 0: Clarify & Triage
+
+### 0.1 Quick Decision: Failure vs Noise
+
+| Signal | Classification | Action |
+|--------|----------------|--------|
+| User flow fails, wrong output, security issue | **Failure (P0/P1)** | Full zero-regression workflow |
+| Flow succeeds but console is noisy | **Noise (P2)** | Feature detection, fallback, log level |
+
+If unclear, ask: **Final outcome?** (A) Fails (B) Succeeds but noisy (C) Succeeds but wrong
+
+### 0.2 Entry Point Disambiguation
+
+> **Which entry point?**
+> (A) UI: page/route → button/menu → expected outcome
+> (B) API: method + endpoint
+> (C) Background: job/cron/task name
+> (D) Not sure (share screenshot/video)
+
+### 0.3 High-Information Question Templates
+
+| User says | Ask (pick 1-2 only) |
+|-----------|---------------------|
+| "Works but console shows red errors" | (1) Final outcome? (A/B/C) (2) Which action triggers the first error? |
+| "Fails when I click X" | (1) Exact UI path? (2) What is the expected output? |
+| "Intermittent / flaky" | (1) Always vs intermittent? (2) Environment? (dev/staging/prod) |
+| "Same log in multiple places" | (1) Which entry points show it? (2) Do ALL of them fail? |
+
+### 0.4 Questioning Rules (NON-NEGOTIABLE)
+
+- Ask **1-2 questions per round** (max)
+- Prefer **multiple-choice** with "Other/Not sure" option
+- **Do not ask user to confirm assumptions** — write them explicitly
+- Request **evidence** (screenshot, log) instead of more guesses
+
+### 0.5 Phase 0 Output Template
+
+```markdown
+## Triage Summary
+- Entry point:
+- Final outcome: (Fail / Succeed but noisy / Succeed but wrong)
+- Classification: (Failure / Noise)
+- Severity: (P0 / P1 / P2) + why
+- 🔄 Collaborating Skills: [from skill router table]
+- 📚 Knowledge Base Match: [from Phase -1]
+- Working hypothesis:
+- Next step:
+```
+
+---
+
+## Phase 4: Fix with Skill Delegation
+
+### 4.1 识别修复需要的额外工作
+
+| 修复需要 | 处理方式 |
+|---------|---------|
+| 仅修改现有代码 | 直接在 bug-fixing 上下文中修复 |
+| 新增 API 接口 | 🔧 委托 `fullstack-developer` |
+| 新增/修改前端组件 | 🔧 委托 `frontend-design` |
+| 数据库 Schema 变更 | 🔧 委托 `database-migrations` |
+| 数据修复 | 🔧 委托 `database-design` |
+| 需要测试 | 🔧 委托 `unit-testing` / `webapp-testing` |
+
+### 4.2 委托执行流程
+
+```
+修复需要额外工作
+       │
+       ▼
+Step 1: 输出委托通知 (Delegation Notice)
+       │ - 锚定主上下文 (Bug ID, 症状, 根因, 当前阶段)
+       │ - 明确委托范围 (✅ 做什么, ❌ 不做什么)
+       │ - 定义退出条件
+       │
+       ▼
+Step 2: 执行委托任务
+       │ - 加载目标技能规范
+       │ - 按最小范围执行
+       │ - 遵守约束 (不超出范围, 保持风格一致)
+       │
+       ▼
+Step 3: 退出检查
+       │ - 是否完成委托目标?
+       │ - 是否超出范围? (如超出, 停止并确认)
+       │ - 输出委托完成通知
+       │
+       ▼
+Step 4: 返回主上下文
+       │ - 继续 bug-fixing 流程
+       │ - 集成委托任务产出
+       │ - 验证修复效果
+```
+
+### 4.3 委托范围约束
+
+| 委托技能 | ✅ 允许 | ❌ 禁止 |
+|---------|--------|--------|
+| `fullstack-developer` | 创建修复所需的最小 API | 重构其他 API、添加额外功能 |
+| `frontend-design` | 修复/创建问题组件 | 重新设计整个页面、更换样式系统 |
+| `database-migrations` | 修复所需的 Schema 变更 | 重构整个数据模型、优化无关表 |
+| `unit-testing` | 添加修复相关的回归测试 | 重写整个测试套件 |
+
+---
+
+## 🔴 委托任务模板
+
+### 进入委托任务时输出：
+
+```markdown
+---
+## 🔧 技能委托通知 (Skill Delegation Notice)
+
+### 主上下文锚定 (Main Context Anchor)
+- **Bug ID**: [BUG-XXX]
+- **原始症状**: [用户报告的问题]
+- **根因**: [已识别的根本原因]
+- **当前阶段**: Phase 4.X - 修复实施
+
+### 委托任务详情 (Delegation Details)
+- **委托技能**: `skill-name`
+- **委托目的**: [目的]
+- **委托范围**: 
+  - ✅ [允许做的]
+  - ❌ [不允许做的]
+- **退出条件**: [完成标准]
+
+### 约束继承
+- 保持现有代码风格
+- 最小 LOC 原则
+- 不引入新依赖 (除非必须)
+
+---
+⏱️ 进入委托任务...
+```
+
+### 退出委托任务时输出：
+
+```markdown
+---
+## ✅ 委托任务完成 (Delegation Complete)
+
+### 完成情况
+- **创建的文件**: [列表]
+- **修改的文件**: [列表]
+- **是否超出范围**: 是/否
+
+### 返回主上下文
+- **继续阶段**: Phase X - [阶段名]
+- **下一步**: [具体动作]
+
+---
+🔄 返回 Bug 修复主上下文...
+```
+
+---
+
+## Phase 6: Knowledge Extraction (MANDATORY)
+
+**每次 Bug 修复后，必须更新 bug-guide.md！**
+
+### 知识提取流程
+
+1. **模式抽象**: 这个 Bug 属于哪个类别?
+2. **通用化描述**: 将项目特定细节抽象为通用模式
+3. **更新 bug-guide.md**: 添加到对应类别表格
+4. **验证可用性**: 下次能通过 Phase -1 找到吗?
+
+### 知识提取模板
+
+```markdown
+## 📝 Phase 6: 知识提取报告
+
+### Bug 基本信息
+- **Bug ID**: BUG-XXX
+- **日期**: YYYY-MM-DD
+- **严重程度**: P0/P1/P2
+
+### 模式抽象
+- **类别**: [现有类别名 或 NEW: 新类别名]
+- **模式名称**: [通用化的模式名称]
+- **典型症状**: [通用化描述]
+- **检测方法**: [如何发现这类 Bug]
+- **修复策略**: [通用化的修复方法]
+
+### bug-guide.md 更新内容
+[将被添加到 bug-guide.md 的具体内容]
+
+### 检查
+- [ ] 模式已添加到 bug-guide.md
+- [ ] 描述足够通用，可复用
+```
+
+### 知识质量标准
+
+| 标准 | 检查问题 |
+|------|---------|
+| **通用性** | 换个项目能理解吗? |
+| **可操作性** | 能直接按步骤执行吗? |
+| **可搜索性** | 用不同关键词能找到吗? |
+| **完整性** | 症状+检测+修复都有吗? |
+
+---
+
+## 🔴 Mandatory Checkpoints
+
+**每个阶段完成前，必须确认对应检查项！**
+
+### Phase -1: Knowledge Query
+- [ ] 已读取 bug-guide.md
+- [ ] 已搜索匹配模式
+- [ ] 已记录匹配结果
+
+### Phase 0: Triage
+- [ ] 已确定入口点
+- [ ] 已分类 (Failure / Noise)
+- [ ] 已评估严重程度
+
+### Phase 1-3: Reproduce & RCA & Scope
+- [ ] 已最小复现
+- [ ] 已识别根因
+- [ ] 已执行全局搜索
+
+### Phase 4: Fix
+- [ ] 所有位置已修复
+- [ ] 委托任务已完成 (如适用)
+- [ ] 格式化 + Lint 通过
+
+### Phase 4.5-4.7: Impact & Completeness & Deps
+- [ ] 已追踪所有调用者
+- [ ] 控制流完整性检查
+- [ ] 新依赖已安装
+
+### Phase 5: Verify
+- [ ] 核心修复验证
+- [ ] 回归测试通过
+- [ ] 🔴 code-review 通过
+
+### Phase 6: Learn
+- [ ] 模式已抽象
+- [ ] bug-guide.md 已更新
+- [ ] 知识可搜索性验证
+
+---
+
+## Complete Output Contract
+
+```markdown
+## 📚 Knowledge Base Query (Phase -1)
+- **匹配结果**: [已有模式名 / 无匹配]
+- **应用策略**: [直接应用 / 参考 / 完整调查]
+
+## Tech Stack
+- Platform: [Web / Desktop / Mobile]
+- Framework: [version]
+- Runtime: [Browser / Node / Tauri / Electron]
+
+## Triage Summary
+- Entry point:
+- Classification: [Failure / Noise]
+- Severity: [P0 / P1 / P2]
+
+## Root Cause
+[1-sentence explanation of WHY it fails]
+
+## Scope Discovery (Global Search)
+- **Search Query Used**: `grep "pattern" path/`
+- **Locations Found**:
+  - `FileA.tsx`
+  - `FileB.tsx`
+
+## Fix Summary
+[What changed]
+
+## 🔧 Skill Delegation Report
+| Delegated Skill | Purpose | Scope | Completed |
+|-----------------|---------|-------|-----------|
+| `frontend-design` | 创建组件 | 仅修复所需 | ✅ |
+
+## Associated Fixes (Proactive)
+[Extra places fixed beyond user's report]
+
+## Impact Analysis
+- **Inventory (Source)**: [modified symbols]
+- **Trace (Radius)**: [affected files]
+- **Verification**: [x] All consumers compatible
+
+## Verification
+- [x] Core fix works
+- [x] All instances fixed
+- [x] No regressions
+- [x] 🔴 code-review passed
+- [x] Real environment tested
+
+## 📝 Knowledge Extraction (Phase 6)
+- **模式类别**: [Category X: Name]
+- **是否更新 bug-guide.md**: ✅ 是
+- **新增内容摘要**: [简要描述]
+
+## 🔒 Checkpoint Verification
+- [x] Phase -1 completed
+- [x] Phase 0-5 completed
+- [x] Phase 6 completed
+- [x] All mandatory checkpoints passed
+```