@tinkcarlos/skillora 0.2.0

package/.claude/skills/bug-fixing/references/config-driven-fixes.md

@@ -0,0 +1,136 @@
+# Configuration-Driven Fixes
+
+Avoid hardcoded solutions. Prefer dynamic, maintainable approaches.
+
+## Why Avoid Hardcoding?
+
+| Hardcoded | Problem |
+|-----------|---------|
+| List of models | New models require code changes |
+| Feature flags in code | Can't change without deploy |
+| Environment-specific logic | Breaks in other environments |
+| Version checks | Breaks when versions change |
+
+## Solution Hierarchy
+
+### 1. Database-Driven (Best)
+
+Store capability/config in database, allowing runtime updates.
+
+```python
+# Model with capability field
+class LLMProvider(Base):
+    supports_tool_calling: bool | None = None
+
+# Service uses field
+if not provider.supports_tool_calling:
+    use_fallback_mode()
+```
+
+**Pros**: User configurable, no code changes needed
+**Cons**: Requires migration for new fields
+
+### 2. Runtime Detection
+
+Probe the system at runtime to detect capabilities.
+
+```python
+async def detect_tool_support(model: str, api_key: str) -> bool:
+    """Probe API to check if model supports tools."""
+    try:
+        response = await client.chat(
+            model=model,
+            messages=[{"role": "user", "content": "test"}],
+            tools=[test_tool_definition],
+        )
+        return "tool_calls" in response
+    except Exception:
+        return False
+```
+
+**Pros**: Always accurate, adapts to changes
+**Cons**: Additional API call, may have latency
+
+### 3. Configuration File
+
+Use YAML/JSON config that can be updated without code changes.
+
+```yaml
+# config/features.yaml
+models:
+  gpt-4:
+    supports_tools: true
+  deepseek-reasoner:
+    supports_tools: false
+```
+
+```python
+def load_model_config(model_name: str) -> dict:
+    config = yaml.safe_load(open("config/features.yaml"))
+    return config["models"].get(model_name, {})
+```
+
+**Pros**: Easy to update, version controlled
+**Cons**: Still requires config changes
+
+### 4. Pattern Matching (Fallback)
+
+When detection is impossible, use pattern matching with clear documentation.
+
+```python
+def infer_capability(model_name: str) -> bool:
+    """
+    Infer capability from model name pattern.
+    
+    Fallback when database config is None and runtime detection 
+    is not available.
+    """
+    patterns = ["reasoner", "r1", "o1-preview", "o1-mini"]
+    return not any(p in model_name.lower() for p in patterns)
+```
+
+**Pros**: No external dependencies
+**Cons**: May need updates when new models appear
+
+### 5. Hardcoded List (Last Resort)
+
+Only use when no other option exists. MUST document why.
+
+```python
+# ⚠️ HARDCODED: Used because XYZ API doesn't support capability detection
+# TODO: Remove when API v2 adds feature detection endpoint
+UNSUPPORTED_MODELS = frozenset(["model-a", "model-b"])
+```
+
+## Migration Pattern
+
+When refactoring from hardcoded to config-driven:
+
+```python
+# Step 1: Add database field
+# Migration: add supports_feature column (nullable)
+
+# Step 2: Use hybrid approach during transition
+def get_feature_support(config) -> bool:
+    # Priority 1: Database config
+    if config.supports_feature is not None:
+        return config.supports_feature
+    
+    # Priority 2: Pattern matching fallback
+    return infer_from_name(config.model_name)
+
+# Step 3: Backfill existing records with proper values
+
+# Step 4: Add runtime detection for new records
+```
+
+## Summary Table
+
+| Approach | Maintenance | Flexibility | Complexity |
+|----------|-------------|-------------|------------|
+| Database field | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐ |
+| Runtime detection | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐ |
+| Config file | ⭐⭐ | ⭐⭐ | ⭐ |
+| Pattern matching | ⭐ | ⭐ | ⭐ |
+| Hardcoded list | ❌ | ❌ | ⭐ |
+

package/.claude/skills/bug-fixing/references/context-isolation-protocol.md

@@ -0,0 +1,268 @@
+# Context Isolation Protocol (上下文隔离协议)
+
+> 确保 Bug 修复过程中调用其他技能时不会丢失主上下文，防止目标漂移和范围膨胀。
+
+---
+
+## 问题背景
+
+### 技能污染 (Skill Pollution) 定义
+
+当修复 Bug 过程中需要调用其他技能时，AI 可能会：
+
+1. **目标漂移 (Goal Drift)**: 开始修复 Bug，但逐渐转向功能开发或重构
+2. **范围膨胀 (Scope Creep)**: 小修复变成大工程，引入更多风险
+3. **上下文丢失 (Context Loss)**: 忘记原始目标，无法正确验证修复效果
+
+### 污染示例
+
+```
+❌ 污染场景：
+
+用户报告：登录按钮点击无响应
+
+AI 行为：
+1. 发现需要修复登录 API ✅
+2. 发现 API 代码"不够好"，开始重构 ❌
+3. 重构过程中发现数据库设计"有问题" ❌
+4. 开始重新设计用户表 ❌
+5. 几个小时后...用户的登录按钮问题还没修复 ❌
+```
+
+---
+
+## 解决方案：上下文隔离架构
+
+### 核心概念
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│  BUG-FIXING MAIN CONTEXT (主上下文)                                     │
+│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
+│                                                                          │
+│  🔒 IMMUTABLE ANCHOR (不可变锚点):                                       │
+│  ┌──────────────────────────────────────────────────────────────────┐   │
+│  │ Bug ID: BUG-001                                                  │   │
+│  │ Original Symptom: 登录按钮点击无响应                              │   │
+│  │ Root Cause: onClick 事件处理函数抛出异常                          │   │
+│  │ Success Criteria: 点击登录按钮后能正常跳转                        │   │
+│  └──────────────────────────────────────────────────────────────────┘   │
+│                                                                          │
+│  📋 EXECUTION STATE (可变执行状态):                                      │
+│  ┌──────────────────────────────────────────────────────────────────┐   │
+│  │ Current Phase: 4.2                                               │   │
+│  │ Delegated Tasks: [frontend-design: pending]                      │   │
+│  │ Completed Tasks: [RCA, Scope Discovery]                          │   │
+│  └──────────────────────────────────────────────────────────────────┘   │
+│                                                                          │
+│  🔧 ISOLATED DELEGATION (隔离委托区):                                    │
+│  ┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┐  │
+│  │ Delegated Skill: frontend-design                                  │  │
+│  │ Purpose: 修复 LoginButton 组件                                    │  │
+│  │ Scope Constraint: 仅修复点击处理，不重构                          │  │
+│  │ Exit Condition: 按钮可点击                                        │  │
+│  └ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┘  │
+│                                                                          │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+### 三层保护机制
+
+| 保护层 | 机制 | 作用 |
+|-------|------|------|
+| **锚点层** | 不可变的 Bug 信息 | 始终记住原始目标 |
+| **约束层** | 委托范围限制 | 防止范围膨胀 |
+| **检查层** | 进入/退出验证 | 确保正确切换上下文 |
+
+---
+
+## 实施规范
+
+### 1. 主上下文初始化
+
+**在 Phase 0 完成后，必须建立主上下文锚点：**
+
+```markdown
+## 🔒 主上下文锚点 (Main Context Anchor)
+
+### 不可变信息
+- **Bug ID**: BUG-XXX
+- **原始症状**: [用户原话]
+- **入口点**: [具体 UI/API/Job]
+- **成功标准**: [如何判断修复成功]
+
+### 当前状态
+- **阶段**: Phase X
+- **根因**: [如已确定]
+- **待修复位置**: [列表]
+```
+
+### 2. 委托前检查
+
+**进入任何委托任务前，必须回答：**
+
+| 检查项 | 必须明确 |
+|-------|---------|
+| **目的** | 这个委托任务是为了修复 Bug 的哪个方面？ |
+| **范围** | 最小必要的工作是什么？ |
+| **禁止** | 明确不能做什么？ |
+| **退出** | 什么标志着委托完成？ |
+| **时间** | 预计需要多少步骤？（超过 3 步需警惕） |
+
+### 3. 委托中监控
+
+**执行委托任务时，持续检查：**
+
+```markdown
+## ⚠️ 范围警戒 (Scope Guard)
+
+每完成一个步骤，问自己：
+1. 这一步是否直接服务于修复 Bug？
+2. 是否在预定范围内？
+3. 是否有"顺便做点其他事"的冲动？
+
+🚨 如果发现超出范围：
+1. 立即停止当前工作
+2. 记录超出范围的发现
+3. 询问用户是否需要单独处理
+4. 返回主上下文继续修复
+```
+
+### 4. 委托后验证
+
+**退出委托任务时，必须验证：**
+
+| 验证项 | 通过标准 |
+|-------|---------|
+| **目标达成** | 委托目的已实现 |
+| **范围遵守** | 未超出预定范围 |
+| **无副作用** | 未引入无关变更 |
+| **可集成** | 产出可直接用于修复 |
+
+---
+
+## 模板和格式
+
+### 委托进入模板
+
+```markdown
+---
+## 🔧 技能委托通知
+
+### 主上下文确认
+- **Bug ID**: BUG-XXX
+- **原始症状**: [...]
+- **根因**: [...]
+- **当前阶段**: Phase X
+
+### 委托详情
+- **目标技能**: `skill-name`
+- **委托目的**: [为什么需要这个技能]
+- **范围限定**:
+  - ✅ [允许做的事情]
+  - ❌ [不允许做的事情]
+- **退出条件**: [什么标志完成]
+- **预计步骤**: X 步
+
+### 约束传递
+- 保持现有代码风格
+- 不引入新依赖 (除非必须)
+- 最小 LOC 原则
+
+---
+⏱️ 开始委托任务...
+```
+
+### 委托退出模板
+
+```markdown
+---
+## ✅ 委托任务完成
+
+### 完成情况
+- **目标达成**: ✅ / ❌
+- **范围遵守**: ✅ / ❌ (如超出，说明原因)
+- **产出物**: [创建/修改的文件列表]
+
+### 超出范围发现 (如有)
+[记录发现但未处理的问题，建议后续单独处理]
+
+### 返回指令
+- **继续阶段**: Phase X.Y
+- **下一步动作**: [具体动作]
+
+---
+🔄 返回 Bug 修复主上下文
+```
+
+---
+
+## 常见污染场景及应对
+
+### 场景 1: "顺便优化"冲动
+
+```
+❌ 污染行为：
+修复 API 返回格式时，发现代码"不够好"，开始重构整个 API 模块。
+
+✅ 正确行为：
+1. 记录发现的"可优化点"
+2. 仅修复必要的返回格式问题
+3. 修复完成后，建议用户单独处理优化
+```
+
+### 场景 2: 连带发现
+
+```
+❌ 污染行为：
+修复登录 Bug 时，发现注册也有类似问题，直接开始修复注册。
+
+✅ 正确行为：
+1. 在 Scope Discovery 阶段记录注册问题
+2. 如果是同一根因，一起修复 ✅
+3. 如果是不同问题，记录为 Related Issue，当前聚焦登录
+```
+
+### 场景 3: 基础设施问题
+
+```
+❌ 污染行为：
+修复前端 Bug 时，发现测试框架配置有问题，开始修复测试配置。
+
+✅ 正确行为：
+1. 如果不影响修复：记录，继续修复 Bug
+2. 如果阻塞修复：最小化解决阻塞，不全面修复配置
+3. 建议后续单独处理测试配置问题
+```
+
+---
+
+## 检查清单
+
+### 委托前
+- [ ] 主上下文锚点已建立
+- [ ] 委托目的明确
+- [ ] 范围限定清晰
+- [ ] 退出条件定义
+
+### 委托中
+- [ ] 每步都在范围内
+- [ ] 未被"优化冲动"带偏
+- [ ] 保持对主上下文的意识
+
+### 委托后
+- [ ] 目标已达成
+- [ ] 范围未超出
+- [ ] 产出可集成
+- [ ] 已返回主上下文
+
+---
+
+## 违规处理
+
+| 违规类型 | 处理方式 |
+|---------|---------|
+| 发现超出范围 | 立即停止，记录，询问用户 |
+| 目标漂移 | 重新读取主上下文锚点，回到正轨 |
+| 范围膨胀 | 收缩到最小必要，其余作为建议 |
+| 上下文丢失 | 重新输出主上下文确认，继续 |

package/.claude/skills/bug-fixing/references/cross-surface-regression.md

@@ -0,0 +1,120 @@
+# Cross-surface Regression Checklist
+
+Fixing a bug in one “surface” (e.g., an API endpoint or a settings page) often introduces regressions in other surfaces that share the same **contract**, **data**, or **behavior**.
+
+This checklist helps you find and validate *all* impacted consumers, so a fix can be shipped once with low risk.
+
+## When to use
+
+Use this checklist when the fix touches any shared artifact:
+
+- An API response/request schema
+- A database model / data shape
+- A shared configuration (feature flags, provider lists, routing rules)
+- A shared UI component or domain hook/store
+- A shared cache key / pagination / sorting rules
+- A shared “list of things” used across multiple screens (settings, runtime selection, admin views, etc.)
+
+## Definitions
+
+- **Surface**: any user-visible or system-visible touchpoint (UI screens, API endpoints, background jobs, CLIs, integrations).
+- **Contract**: the expectations that connect a producer to its consumers (types, schema, invariants, default behavior).
+- **Consumer inventory**: a complete list of places that depend on the same contract/data.
+
+## Step 1 — Identify the shared contract/data
+
+Write this down explicitly (1–3 sentences):
+
+- What changed? (field name, endpoint behavior, allowed values, sorting, auth, error shape)
+- What must remain stable? (backward compatibility constraints)
+- What is the “source of truth”? (API, DB, config file, derived cache)
+
+## Step 2 — Build a consumer inventory (the critical step)
+
+List every consumer that reads/derives the same contract/data.
+
+- **UI consumers**
+  - List view(s)
+  - Detail view(s)
+  - Settings/config page(s)
+  - Selection drop-down(s) / pickers / modals
+  - Export/download flows
+- **API consumers**
+  - Public endpoints
+  - Internal services/clients
+  - SDK calls (if any)
+- **Background consumers**
+  - Jobs/tasks/cron
+  - Async pipelines (analysis, indexing, etc.)
+- **Operational consumers**
+  - Admin dashboards
+  - Metrics/alerts/log parsers
+  - Migrations/backfills
+
+### Consumer inventory template
+
+Fill a table like this:
+
+| Consumer | Surface type | Entry point | Uses what? | Risk level | Verification |
+|---|---|---|---|---|---|
+| UI: selection picker | UI | route → control | reads list, filters by status | high | manual + unit |
+| API: status endpoint | API | GET /… | returns updated fields | high | contract test |
+| background analyzer | job | task name | expects enum values | medium | integration smoke |
+
+## Step 3 — Define a minimal regression matrix per consumer
+
+For each **high-risk** consumer, verify the smallest set of cases that catch 80% of regressions:
+
+- **Happy path**: typical request with typical data
+- **Empty state**: no items / no results
+- **Pagination**: first page vs subsequent page (if applicable)
+- **Sorting**: default sort and one explicit sort parameter (if applicable)
+- **Filtering**: the most common filter path (if applicable)
+- **Permissions**: allowed vs forbidden user/role (if applicable)
+- **Error shape**: one representative error should still be actionable and consistent
+
+## Step 4 — Check cross-surface invariants
+
+These are common “looks fine here, broken there” causes:
+
+- **Field naming drift**: one surface uses `analysis_status`, another expects `status`
+- **Default values**: missing fields vs explicit `null` vs omitted keys
+- **Compatibility fallbacks**: legacy fields overriding new mappings
+- **Caching**: stale cache keys; different TTLs; inconsistent invalidation triggers
+- **Feature flags**: enabled in one surface but not in another
+- **Versioned base URLs**: `/v1` vs `/v4`; accidental double-prefixing
+
+## Step 5 — Add the smallest automated guardrail
+
+Pick one (or more) that best matches the contract:
+
+- **Contract tests**: assert response shape and key invariants across versions
+- **Unit tests**: URL builders, mappers, parsing logic, fallbacks
+- **Integration smoke**: critical path end-to-end for the shared contract
+
+Rule of thumb: if the bug involved a **mapping/fallback**, add a unit test that locks the mapping behavior.
+
+## Similar-bug hunt (recommended)
+
+After the fix, search for the same pattern elsewhere:
+
+- URL construction patterns (e.g., `/v1` joining, trailing slashes)
+- Field fallback logic (legacy vs new config)
+- Consumer parsing assumptions (lists vs dicts, optional vs required)
+
+Example search prompts (adapt to repo conventions):
+
+- `"legacy" AND "fallback" AND "<field_name>"`
+- `"base_url" AND "v1" AND "join"`
+- `"model_map" OR "mapping" OR "selector"`
+- `"analysis_status" AND ("list" OR "dropdown" OR "picker")`
+
+## Definition of Done (cross-surface)
+
+You are not “done” until:
+
+- Every **high-risk consumer** in your inventory has a pass/fail outcome recorded
+- At least one **automated guardrail** exists for the root cause (or a justified exception)
+- The fix does not introduce new inconsistencies between list/detail/settings/selection surfaces
+
+

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

@@ -0,0 +1,129 @@
+# Database Investigation Guide
+
+Bugs often originate from database schema, migrations, or data issues.
+
+## What to Check
+
+### 1. Schema Definition
+
+| Location | Description |
+|----------|-------------|
+| `migrations/` | Migration history |
+| `alembic/versions/` | Alembic migrations (Python) |
+| `*.sql` | Raw SQL scripts |
+| `models/` | ORM model definitions |
+| `entities/` | Entity definitions |
+
+**Key Questions**:
+- Does the DB column exist?
+- Is the type correct?
+- Are constraints appropriate?
+- Is the index present for query performance?
+
+### 2. Migration Status
+
+```bash
+# Alembic (Python)
+alembic current
+alembic history
+
+# Django
+python manage.py showmigrations
+
+# TypeORM
+npm run typeorm migration:show
+
+# Sequelize
+npx sequelize db:migrate:status
+```
+
+### 3. Compare ORM vs Actual DB
+
+```sql
+-- PostgreSQL: Check actual column
+SELECT column_name, data_type, is_nullable
+FROM information_schema.columns
+WHERE table_name = 'your_table';
+
+-- SQLite: Check schema
+.schema your_table
+
+-- MySQL: Check schema
+DESCRIBE your_table;
+```
+
+## Common Database Bugs
+
+### Missing Field
+
+**Symptom**: `column does not exist`
+
+**Investigation**:
+1. Check if field exists in ORM model
+2. Check if migration was created
+3. Check if migration was applied
+
+**Fix**:
+```bash
+# Create migration
+alembic revision --autogenerate -m "add_field_name"
+
+# Apply migration
+alembic upgrade head
+```
+
+### Type Mismatch
+
+**Symptom**: Data truncation, constraint violation
+
+**Investigation**:
+1. Compare ORM field type vs DB column type
+2. Check data being inserted
+
+**Fix**: Create migration to alter column type
+
+### Missing Index
+
+**Symptom**: Slow queries
+
+**Investigation**:
+```sql
+EXPLAIN ANALYZE SELECT * FROM table WHERE field = 'value';
+```
+
+**Fix**: Add index in migration
+
+### Constraint Violation
+
+**Symptom**: `violates not-null constraint`, `unique constraint`
+
+**Investigation**:
+1. Check constraint definition
+2. Check data being inserted
+3. Check if default value is needed
+
+## Migration Best Practices
+
+```python
+# Always set PYTHONPATH when running alembic
+# Windows
+set PYTHONPATH=.\backend
+alembic upgrade head
+
+# Linux/macOS
+PYTHONPATH=./backend alembic upgrade head
+```
+
+## Data Investigation
+
+```sql
+-- Check for null values
+SELECT COUNT(*) FROM table WHERE field IS NULL;
+
+-- Check for duplicates
+SELECT field, COUNT(*) FROM table GROUP BY field HAVING COUNT(*) > 1;
+
+-- Check data distribution
+SELECT field, COUNT(*) FROM table GROUP BY field ORDER BY COUNT(*) DESC LIMIT 10;
+```
+