@tinkcarlos/skillora 0.2.0

package/.claude/skills/fullstack-developer/references/code-quality-checklist.md

@@ -0,0 +1,271 @@
+# Code Quality Checklist
+
+Detailed guidelines for common code quality issues that often escape initial development but are caught during code review.
+
+## 1. Exception Handling Best Practices
+
+### Python
+
+| Pattern | Bad | Good |
+|---------|-----|------|
+| Bare except | `except Exception:` | `except (ValueError, TypeError) as e:` |
+| Silent catch | `except: pass` | `except SomeError as e: logger.warning(...)` |
+| No context | `except E: log("failed")` | `except E as e: log(f"failed: {e}")` |
+
+**Exception Hierarchy Examples:**
+
+```python
+# File operations
+except (FileNotFoundError, PermissionError, IOError) as e:
+
+# Network operations
+except (ConnectionError, TimeoutError, aiohttp.ClientError) as e:
+
+# JSON/encoding
+except (json.JSONDecodeError, UnicodeDecodeError) as e:
+
+# Base64
+except (binascii.Error, UnicodeDecodeError) as e:
+
+# Database
+except (sqlalchemy.exc.IntegrityError, sqlalchemy.exc.OperationalError) as e:
+```
+
+### TypeScript/JavaScript
+
+| Pattern | Bad | Good |
+|---------|-----|------|
+| Catch all | `catch (e) {}` | `catch (e) { if (e instanceof TypeError) ... }` |
+| Silent | `catch {}` | `catch (e) { console.warn('Context:', e) }` |
+| No rethrow | swallow unexpected | `throw e` for unexpected errors |
+
+**Best Practice:**
+
+```typescript
+try {
+  await someOperation();
+} catch (e) {
+  if (e instanceof NetworkError) {
+    // Handle network errors specifically
+    showRetryDialog();
+  } else if (e instanceof ValidationError) {
+    // Handle validation errors
+    showValidationMessage(e.message);
+  } else {
+    // Log unexpected errors and rethrow
+    console.error('Unexpected error:', e);
+    throw e;
+  }
+}
+```
+
+---
+
+## 2. Performance Anti-patterns
+
+### Regex on Large Text
+
+**Problem:** Regex `.sub()` or `.match()` on large text (>1MB) can be expensive.
+
+**Solution:** Add early-exit checks:
+
+```python
+def process_patterns(text: str) -> str:
+    if not text:
+        return text
+    
+    # Early exit: skip expensive regex if pattern marker not present
+    if '${' not in text:  # or whatever marker indicates patterns exist
+        return text
+    
+    # Now safe to run regex
+    return PATTERN.sub(replacer, text)
+```
+
+### Loop Performance
+
+| Anti-pattern | Better |
+|--------------|--------|
+| Nested loops O(n²) | Use dict/set for O(1) lookup |
+| Repeated DB queries in loop | Batch query outside loop |
+| String concatenation in loop | Use list + join |
+| Import inside loop | Import at module level |
+
+**Example - Batch Query:**
+
+```python
+# Bad: N+1 queries
+for item in items:
+    related = db.query(Related).filter(Related.item_id == item.id).first()
+
+# Good: Single query + dict lookup
+related_map = {r.item_id: r for r in db.query(Related).filter(
+    Related.item_id.in_([i.id for i in items])
+).all()}
+for item in items:
+    related = related_map.get(item.id)
+```
+
+---
+
+## 3. UX Feedback Patterns
+
+### User Action Feedback
+
+Every user action should have immediate visual feedback:
+
+| Action | Required Feedback |
+|--------|------------------|
+| Button click | Loading state, disable during action |
+| Form submit | Loading indicator, success/error message |
+| Copy to clipboard | "Copied!" indicator (toast or inline) |
+| Delete | Confirmation dialog, success message |
+| Save | Saving indicator, saved confirmation |
+
+### Copy to Clipboard Pattern
+
+```typescript
+const [copied, setCopied] = useState(false);
+
+const copyToClipboard = (text: string) => {
+  navigator.clipboard.writeText(text);
+  setCopied(true);
+  setTimeout(() => setCopied(false), 2000);
+};
+
+// In JSX:
+<button onClick={() => copyToClipboard(value)}>
+  {copied ? '✓ Copied!' : 'Copy'}
+</button>
+```
+
+### Keyboard Support Checklist
+
+| Component | Required Keys |
+|-----------|---------------|
+| Modal/Dialog | ESC to close |
+| Dropdown | ESC to close, Enter to select, Arrow keys to navigate |
+| Form | Enter to submit (when appropriate) |
+| List | Arrow keys to navigate, Enter to select |
+| Search | ESC to clear |
+
+**Implementation:**
+
+```typescript
+useEffect(() => {
+  const handleKeyDown = (e: KeyboardEvent) => {
+    if (e.key === 'Escape') {
+      onClose();
+    }
+  };
+  
+  document.addEventListener('keydown', handleKeyDown);
+  return () => document.removeEventListener('keydown', handleKeyDown);
+}, [onClose]);
+```
+
+---
+
+## 4. Frontend-Backend Data Sync Verification
+
+### Problem
+
+Duplicated data definitions across frontend and backend lead to sync issues:
+- Function lists
+- Enum values
+- Status codes
+- Error types
+- Configuration options
+
+### Verification Steps
+
+1. **Identify Shared Data:**
+   ```bash
+   # Search for duplicated definitions
+   grep -r "BUILTIN_FUNCTIONS\|FUNCTION_LIST" frontend/ backend/
+   grep -r "StatusCode\|ErrorType" frontend/ backend/
+   ```
+
+2. **Compare Definitions:**
+   - Count items: do both lists have same length?
+   - Check names: are all names identical?
+   - Check values: are all values/descriptions identical?
+
+3. **Single Source of Truth Options:**
+
+   | Approach | When to Use |
+   |----------|-------------|
+   | Backend generates, frontend fetches | Dynamic data, rarely changes |
+   | Shared JSON/YAML file | Static config, import in both |
+   | OpenAPI/JSON Schema | API contracts |
+   | Code generation | Strong typing requirements |
+
+### Example: Shared Constants
+
+**Option A: Backend API endpoint**
+
+```python
+# Backend: /api/meta/functions
+@router.get("/functions")
+def get_builtin_functions():
+    return [{"name": f, "syntax": s, "desc": d} for f, s, d in BUILTIN_FUNCS]
+```
+
+```typescript
+// Frontend: Fetch on init
+const [functions, setFunctions] = useState([]);
+useEffect(() => {
+  api.get('/meta/functions').then(r => setFunctions(r.data));
+}, []);
+```
+
+**Option B: Shared JSON file**
+
+```json
+// shared/builtin-functions.json
+[
+  {"name": "timestamp", "syntax": "${__timestamp}", "description": "Milliseconds"}
+]
+```
+
+```python
+# Backend
+with open('shared/builtin-functions.json') as f:
+    BUILTIN_FUNCTIONS = json.load(f)
+```
+
+```typescript
+// Frontend
+import functions from '../shared/builtin-functions.json';
+```
+
+---
+
+## 5. Quick Reference Card
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│ Code Quality Quick Checks                                            │
+├─────────────────────────────────────────────────────────────────────┤
+│  EXCEPTIONS:                                                         │
+│  - Specific type? (not bare Exception)                              │
+│  - Logged with context?                                             │
+│  - Unexpected errors rethrown?                                      │
+│                                                                      │
+│  PERFORMANCE:                                                        │
+│  - Early exit before expensive ops?                                 │
+│  - No N+1 queries?                                                  │
+│  - No O(n²) loops?                                                  │
+│                                                                      │
+│  UX FEEDBACK:                                                        │
+│  - Loading states for async?                                        │
+│  - Copy shows confirmation?                                         │
+│  - ESC closes modals/dropdowns?                                     │
+│                                                                      │
+│  DATA SYNC:                                                          │
+│  - Shared constants identical?                                      │
+│  - Single source of truth?                                          │
+│  - Grep for duplicates?                                             │
+└─────────────────────────────────────────────────────────────────────┘
+```
+

package/.claude/skills/fullstack-developer/references/complete-development-workflow.md

@@ -0,0 +1,278 @@
+# Complete Development Workflow Protocol
+
+## 核心原则
+
+**所有开发任务必须走完整流程，确保质量和可追溯性。**
+
+---
+
+## 完整开发流程 (6 阶段)
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Phase 1: 需求分析 (MANDATORY)                               │
+│  ─────────────────────────────────────────────────────────  │
+│  调用: `product-requirements`                                │
+│  输出: 需求文档 + 验收标准                                    │
+└─────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────┐
+│  Phase 2: 可行性分析 + 多方案设计                            │
+│  ─────────────────────────────────────────────────────────  │
+│  1. 代码库分析 (使用 MCP serena 工具)                        │
+│  2. 技术可行性评估                                           │
+│  3. 提供 2-3 个方案供用户选择                                │
+│  输出: 方案对比表 + 推荐方案                                  │
+└─────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────┐
+│  Phase 3: 详细计划制定                                       │
+│  ─────────────────────────────────────────────────────────  │
+│  根据用户选择的方案:                                         │
+│  1. 深度代码解析                                             │
+│  2. 制定任务分解计划                                         │
+│  3. 明确每个任务调用的 Skills                                │
+│  输出: 实施计划文档                                          │
+└─────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────┐
+│  Phase 4: 开发执行 (按计划逐步执行)                          │
+│  ─────────────────────────────────────────────────────────  │
+│  For each task:                                             │
+│    1. 调用对应 Skill 执行开发                                │
+│    2. 完成后立即执行测试                                     │
+│    3. 输出任务完成确认                                       │
+└─────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────┐
+│  Phase 5: 测试验证 (MANDATORY)                               │
+│  ─────────────────────────────────────────────────────────  │
+│  1. 单元测试 (每个任务完成后)                                │
+│  2. 接口测试 (API 开发后)                                    │
+│  3. Web 自动化测试 (前端开发后)                              │
+│  调用: `test-driven-development` + `api-testing-observability`│
+└─────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────┐
+│  Phase 6: 代码审查 + 修复 (MANDATORY)                        │
+│  ─────────────────────────────────────────────────────────  │
+│  调用: `code-review` → 发现问题 → `bug-fixing` → 循环        │
+│  输出: 审查报告 + 修复确认                                    │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Phase 1: 需求分析
+
+### 触发条件
+- 所有开发任务（无论简单复杂）
+
+### 执行步骤
+1. 调用 `product-requirements` 技能
+2. 分析用户需求，提取核心目标
+3. 定义验收标准（Gherkin 格式）
+4. 输出需求文档
+
+### 输出模板
+```markdown
+## 需求分析报告
+
+### 1. 核心目标
+[用户真正想要解决的问题]
+
+### 2. 功能需求
+| ID | 需求 | 优先级 |
+|----|------|--------|
+| F1 | ... | P0 |
+
+### 3. 验收标准
+```gherkin
+Given [前置条件]
+When [用户操作]
+Then [预期结果]
+```
+
+### 4. 约束条件
+- 技术栈: ...
+- 时间: ...
+- 其他: ...
+```
+
+---
+
+## Phase 2: 可行性分析 + 多方案设计
+
+### 执行步骤
+1. 使用 MCP serena 工具分析代码库
+   - `mcp__serena__get_symbols_overview` - 获取文件概览
+   - `mcp__serena__find_symbol` - 查找相关符号
+   - `mcp__serena__find_referencing_symbols` - 查找调用关系
+2. 评估技术可行性
+3. 设计 2-3 个方案
+4. 提供方案对比表
+
+### 输出模板
+```markdown
+## 可行性分析报告
+
+### 1. 代码库分析
+| 模块 | 相关文件 | 影响范围 |
+|------|----------|----------|
+| ... | ... | ... |
+
+### 2. 技术可行性
+| 方面 | 评估 | 风险 |
+|------|------|------|
+| 技术栈兼容 | ✅/⚠️/❌ | ... |
+| 依赖冲突 | ✅/⚠️/❌ | ... |
+| 性能影响 | ✅/⚠️/❌ | ... |
+
+### 3. 方案对比
+| 方案 | 描述 | 难度 | 工作量 | 优点 | 缺点 |
+|------|------|------|--------|------|------|
+| A | ... | 低/中/高 | ... | ... | ... |
+| B | ... | 低/中/高 | ... | ... | ... |
+| C | ... | 低/中/高 | ... | ... | ... |
+
+### 4. 推荐方案
+**推荐方案 X**，原因：...
+
+请选择：
+- [ ] A: [方案A简述]
+- [ ] B: [方案B简述]
+- [ ] C: [方案C简述]
+- [ ] 其他：___
+```
+
+---
+
+## Phase 3: 详细计划制定
+
+### 执行步骤
+1. 根据用户选择的方案
+2. 深度解析相关代码
+3. 分解任务
+4. 为每个任务指定调用的 Skills
+
+### 输出模板
+```markdown
+## 实施计划
+
+### 选定方案
+[用户选择的方案]
+
+### 任务分解
+| # | 任务 | 调用 Skills | 测试类型 | 预计文件 |
+|---|------|-------------|----------|----------|
+| 1 | 数据库设计 | `database-migrations` | 单元测试 | models/*.py |
+| 2 | API 开发 | `api-scaffolding` + `api-testing-observability` | 接口测试 | routes/*.py |
+| 3 | 前端页面 | `frontend-design` | Web 自动化 | components/*.tsx |
+| 4 | 集成测试 | `test-driven-development` | E2E | tests/*.py |
+
+### 执行顺序
+1. Task 1 → 测试 → 确认
+2. Task 2 → 测试 → 确认
+3. ...
+
+### 风险点
+| 风险 | 缓解措施 |
+|------|----------|
+| ... | ... |
+```
+
+---
+
+## Phase 4: 开发执行
+
+### 执行规则
+1. 严格按计划顺序执行
+2. 每个任务完成后立即测试
+3. 测试通过后输出确认
+4. 遵循开发规范（引用 code-review/bug-fixing）
+
+### 任务完成确认模板
+```markdown
+## Task X 完成确认
+
+### 任务
+[任务描述]
+
+### 调用的 Skills
+- `skill-name-1`
+- `skill-name-2`
+
+### 修改的文件
+| 文件 | 变更类型 |
+|------|----------|
+| ... | 新增/修改/删除 |
+
+### 测试结果
+| 测试类型 | 状态 | 覆盖率 |
+|----------|------|--------|
+| 单元测试 | ✅/❌ | X% |
+| 接口测试 | ✅/❌ | - |
+
+### 下一步
+继续 Task X+1
+```
+
+---
+
+## Phase 5: 测试验证
+
+### 测试类型路由
+| 开发类型 | 必须测试 | 调用 Skills |
+|----------|----------|-------------|
+| 后端逻辑 | 单元测试 | `test-driven-development` |
+| API 接口 | 接口测试 | `api-testing-observability` |
+| 前端页面 | Web 自动化 | `webapp-testing` (如有) |
+| 数据库 | 迁移测试 | `database-migrations` |
+
+### 测试通过标准
+| 类型 | 通过标准 |
+|------|----------|
+| 单元测试 | 覆盖率 ≥ 80%，全部通过 |
+| 接口测试 | 所有端点响应正确 |
+| Web 自动化 | 关键流程全部通过 |
+
+---
+
+## Phase 6: 代码审查 + 修复
+
+### 执行流程
+```
+code-review
+    ↓
+发现问题? ─── 是 ──→ bug-fixing ──→ 返回 code-review
+    │
+    否
+    ↓
+审查通过 ✅
+```
+
+### 审查标准引用
+→ 开发规范: `../code-review/references/common-patterns.md`
+→ 常见问题: `../bug-fixing/references/common-bugs.md`
+→ 分层检查: `../code-review/references/layered-checklist-protocol.md`
+
+---
+
+## 开发规范引用 (避免常见问题)
+
+### 来自 code-review
+| 规范 | 引用路径 |
+|------|----------|
+| 通用模式 | `../code-review/references/common-patterns.md` |
+| 后端问题 | `../code-review/references/backend-common-issues.md` |
+| 前端问题 | `../code-review/references/frontend-common-issues.md` |
+| 隐藏 Bug | `../code-review/references/hidden-bugs-detection.md` |
+| 分层检查 | `../code-review/references/layered-checklist-protocol.md` |
+
+### 来自 bug-fixing
+| 规范 | 引用路径 |
+|------|----------|
+| 常见 Bug | `../bug-fixing/references/common-bugs.md` |
+| Bug 指南 | `../bug-fixing/references/bug-guide.md` |
+| RCA 指南 | `../bug-fixing/references/rca-guide.md` |
+| 修复清单 | `../bug-fixing/references/fix-completeness-checklist.md` |