@tinkcarlos/skillora 0.2.0

package/.claude/skills/brainstorming/SKILL.md

@@ -0,0 +1,283 @@
+---
+name: brainstorming
+description: |
+  Turn ideas into fully formed designs through collaborative dialogue.
+  ⚡ QUICK MODE: For rapid design exploration (< 1 hour tasks)
+
+  Use when:
+  - Starting any creative work (features, components, functionality)
+  - Before writing any code
+  - When requirements are unclear or incomplete
+  - Quick design exploration without formal PRD
+
+  Key Features:
+  - Socratic questioning (one question at a time)
+  - Multiple choice questions preferred
+  - Design presented in 200-300 word sections
+  - YAGNI ruthlessly applied
+
+  Output: `docs/plans/YYYY-MM-DD-<topic>-design.md`
+
+  ⚠️ Boundary with product-requirements:
+  - brainstorming: Quick exploration, informal design (< 1 hour)
+  - product-requirements: Formal PRD, competitive analysis, user stories (> 1 hour)
+allowed-tools: [read, write, execute, grep, glob]
+---
+
+# Brainstorming Ideas Into Designs
+
+**Core Principle**: Turn ideas into fully formed designs and specs through natural collaborative dialogue.
+
+## When to Use
+
+**ALWAYS before any creative work:**
+- Creating features
+- Building components
+- Adding functionality
+- Modifying behavior
+
+**Announce at start:** "I'm using the brainstorming skill to refine this idea into a design."
+
+## The Process
+
+```
+1. Understand the idea (ask questions)
+2. Explore approaches (propose alternatives)
+3. Present design (in sections)
+4. Document (save design)
+5. Handoff (to implementation)
+```
+
+## Phase 1: Understanding the Idea
+
+### Check Project Context First
+
+Before asking questions:
+
+```bash
+# Check recent commits
+git log --oneline -10
+
+# Check existing docs
+ls docs/
+
+# Check project structure
+ls -la src/
+```
+
+### Ask Questions One at a Time
+
+**NEVER ask multiple questions at once.**
+
+❌ Bad:
+> "What's the purpose? Who are the users? What's the timeline? Any constraints?"
+
+✅ Good:
+> "What problem does this feature solve for users?"
+
+### Prefer Multiple Choice
+
+When possible, offer options:
+
+> "For the authentication method, which approach fits best?
+> 1. JWT tokens (stateless, good for APIs)
+> 2. Session cookies (simpler, good for web apps)
+> 3. OAuth only (delegate to providers)
+> 4. Something else?"
+
+### Key Questions to Ask
+
+| Area | Question |
+|------|----------|
+| Purpose | "What problem does this solve?" |
+| Users | "Who will use this and how?" |
+| Success | "How will we know it's working?" |
+| Constraints | "Any technical or business constraints?" |
+| Existing | "What similar features exist we can learn from?" |
+
+## Phase 2: Exploring Approaches
+
+### Propose 2-3 Alternatives
+
+Always present options with trade-offs:
+
+```markdown
+## Approach Options
+
+### Option 1: [Name] (Recommended)
+**How it works:** [Brief description]
+**Pros:** [List]
+**Cons:** [List]
+**Best for:** [Use case]
+
+### Option 2: [Name]
+**How it works:** [Brief description]
+**Pros:** [List]
+**Cons:** [List]
+**Best for:** [Use case]
+
+### Option 3: [Name]
+**How it works:** [Brief description]
+**Pros:** [List]
+**Cons:** [List]
+**Best for:** [Use case]
+
+**My recommendation:** Option 1 because [reasoning]
+```
+
+### Apply YAGNI Ruthlessly
+
+For each proposed feature, ask:
+> "Do we need this for the initial version, or can it wait?"
+
+Remove anything that's not essential for v1.
+
+## Phase 3: Presenting the Design
+
+### Break Into 200-300 Word Sections
+
+Present design incrementally, validating after each section:
+
+```markdown
+## Section 1: Architecture Overview
+
+[200-300 words describing high-level architecture]
+
+**Does this architecture approach look right before I continue?**
+```
+
+Wait for confirmation before proceeding.
+
+### Sections to Cover
+
+1. **Architecture Overview** - High-level structure
+2. **Components** - What pieces exist
+3. **Data Flow** - How data moves
+4. **API/Interface** - How components communicate
+5. **Error Handling** - What can go wrong
+6. **Testing Strategy** - How to verify
+
+### Validation After Each Section
+
+After each section:
+> "Does this look right? Any concerns before I continue to [next section]?"
+
+## Phase 4: Documentation
+
+### Save Design Document
+
+```bash
+# Create docs directory if needed
+mkdir -p docs/plans
+
+# Save design
+# File: docs/plans/YYYY-MM-DD-<topic>-design.md
+```
+
+### Design Document Template
+
+```markdown
+# [Feature Name] Design
+
+**Date:** YYYY-MM-DD
+**Status:** Approved / Draft
+**Author:** [Name]
+
+## Problem Statement
+[What problem this solves]
+
+## Goals
+- [Goal 1]
+- [Goal 2]
+
+## Non-Goals (YAGNI)
+- [Thing we're NOT doing]
+- [Another thing we're NOT doing]
+
+## Architecture
+[Architecture description]
+
+## Components
+[Component descriptions]
+
+## Data Flow
+[How data moves]
+
+## API/Interface
+[API definitions]
+
+## Error Handling
+[Error scenarios and handling]
+
+## Testing Strategy
+[How to test]
+
+## Open Questions
+- [Any unresolved questions]
+
+## Decision Log
+| Decision | Rationale | Date |
+|----------|-----------|------|
+| [Decision] | [Why] | [When] |
+```
+
+### Commit the Design
+
+```bash
+git add docs/plans/YYYY-MM-DD-<topic>-design.md
+git commit -m "docs: add <topic> design document"
+```
+
+## Phase 5: Implementation Handoff
+
+After design is approved:
+
+```markdown
+## Design Complete
+
+**Document:** `docs/plans/YYYY-MM-DD-<topic>-design.md`
+
+**Ready to set up for implementation?**
+
+Next steps:
+1. `/using-git-worktrees` - Create isolated workspace
+2. `/writing-plans` - Create detailed implementation plan
+```
+
+## Key Principles
+
+| Principle | Meaning |
+|-----------|---------|
+| **One question at a time** | Never overwhelm with multiple questions |
+| **Multiple choice preferred** | Easier to answer, faster iteration |
+| **YAGNI ruthlessly** | Remove unnecessary features |
+| **200-300 word sections** | Digestible chunks |
+| **Validate incrementally** | Confirm before continuing |
+| **Be flexible** | Adapt to user's communication style |
+
+## Output Contract
+
+```markdown
+## Brainstorming Complete
+
+**Design Document:** `docs/plans/YYYY-MM-DD-<topic>-design.md`
+
+**Summary:**
+- Problem: [One sentence]
+- Solution: [One sentence]
+- Key decisions: [List]
+
+**Ready for:**
+- [ ] `/using-git-worktrees` - Create workspace
+- [ ] `/writing-plans` - Create implementation plan
+```
+
+## Red Flags - Pause and Clarify
+
+- User seems uncertain about requirements
+- Conflicting requirements detected
+- Scope creep happening
+- Technical constraints unclear
+
+When in doubt:
+> "I want to make sure I understand correctly. [Clarifying question]?"

package/.claude/skills/bug-fixing/SKILL.md

@@ -0,0 +1,382 @@
+---
+name: bug-fixing
+user-invocable: true
+description: |
+  Zero-regression bug fixing with context-isolated skill delegation.
+  
+  Use when:
+  - Feature fails, behaves incorrectly, or produces wrong output
+  - "fix bug", "debug", "not working", "error", "broken"
+  - Console shows errors/warnings (even if feature "works")
+  - Performance degradation or timeout issues
+  
+  Key Features:
+  - Phase -1: Query bug-guide.md before investigation
+  - Context-isolated skill delegation (prevents goal drift)
+  - Mandatory code-review after every fix
+  - Phase 6: Knowledge extraction to bug-guide.md
+  
+  Not for: new feature development, refactoring, optimization without bugs.
+allowed-tools: [read, write, execute, grep, glob]
+---
+
+# Bug Fixing – Zero Regression Protocol
+
+**Core Promise**: Fix completely. Fix everywhere. Break nothing. Learn forever.
+
+## The Iron Law
+
+```
+NO FIX WITHOUT ROOT CAUSE INVESTIGATION FIRST
+```
+
+If you're tempted to "just try this fix"? **STOP.** Find the root cause first. Symptom fixes are failures.
+
+## 🔴 Failure Escalation Protocol
+
+| 失败次数 | 动作 |
+|---------|------|
+| 1次 | 重试，检查假设 |
+| 2次 | 扩大调查范围 |
+| 3次 | **停止！质疑架构/设计** |
+
+**3次修复失败后必须:**
+1. 暂停当前修复
+2. 重新审视问题定义
+3. 考虑是否需要重新设计
+4. 询问用户是否继续
+
+### Pair Debugging (协作调试)
+
+**当独自调试陷入僵局时：**
+
+| 技术 | 方法 | 适用场景 |
+|------|------|----------|
+| **Rubber Duck** | 向橡皮鸭/AI 解释问题 | 理清思路 |
+| **Fresh Eyes** | 请同事审查代码 | 发现盲点 |
+| **Time Box** | 休息后重新审视 | 打破思维定式 |
+
+```
+独自调试 30 分钟无进展
+       ↓
+Step 1: Rubber Duck - 向 AI 解释问题
+       ↓
+Step 2: 仍无进展 → 请同事 Review
+       ↓
+Step 3: 仍无进展 → 休息 15 分钟后重试
+```
+
+> "A quick walk or working on something else can lead to 'aha' moments"
+
+## Decision Tree
+
+```
+Bug Report → Phase -1: Query bug-guide.md (MANDATORY)
+                ↓
+         Phase 0: Triage (Failure vs Noise)
+                ↓
+         Phase 1-3: Reproduce → RCA → Scope Discovery
+                ↓
+         Phase 4: Fix (with Skill Delegation if needed)
+                ↓
+         Phase 5: Verify + code-review (MANDATORY)
+                ↓
+         Phase 6: Knowledge Extraction (MANDATORY)
+```
+
+## Core Workflow
+
+| Phase | Goal | Reference |
+|-------|------|-----------|
+| **-1** | Query bug-guide.md | `references/knowledge-extraction-guide.md` |
+| **0** | Triage: Failure vs Noise | `references/investigation-checklist.md` |
+| **1** | Reproduce | - |
+| **2** | RCA (5 Whys + 鱼骨图) | `../shared-references/advanced-debugging-techniques.md` |
+| **3** | Scope Discovery | `references/similar-bug-patterns.md` |
+| **4** | Fix + Skill Delegation | `references/skill-delegation-guide.md` |
+| **4.5-4.7** | Impact + Completeness + Deps | `references/fix-completeness-checklist.md` |
+| **5** | Verify + code-review | `references/zero-regression-matrix.md` |
+| **6** | Knowledge Extraction | `references/knowledge-extraction-guide.md` |
+
+## 🔴 技能编排 (Skill Orchestration)
+
+| 触发条件 | 调用技能 | 返回条件 |
+|----------|----------|----------|
+| 修复需要新 API | `fullstack-developer` | 最小 API 完成 |
+| 修复涉及 UI | `frontend-design` | UI 修复完成 |
+| 修复涉及数据库 | `database-migration` | 迁移完成 |
+| 需要回归测试 | `test-driven-development` | 测试通过 |
+| 修复完成 | 🔴 `code-review` (强制) | 审查通过 |
+| 审查通过 | `verification-before-completion` | 验证通过 |
+
+**返回条件**: 修复验证通过后返回调用方 (code-review/fullstack-developer)
+
+→ 完整协议: `../shared-references/skill-orchestration-protocol.md`
+
+---
+
+## 🔴 Skill Delegation Router
+
+| Fix Requires | Delegate To | Constraint |
+|--------------|-------------|------------|
+| New API | `fullstack-developer` | Minimal API only |
+| Frontend change | `frontend-design` | Fix-related only |
+| Schema change | `database-migrations` | Required changes only |
+| Tests | `unit-testing` / `webapp-testing` | Regression tests only |
+| **After fix** | 🔴 `code-review` | MANDATORY |
+
+→ Full protocol: `references/skill-delegation-guide.md`
+
+## 🔴 Context Isolation (Prevents Goal Drift)
+
+When delegating to other skills, ALWAYS:
+1. Output **Delegation Notice** (anchor main context)
+2. Define **scope constraints** (✅ do / ❌ don't)
+3. Output **Completion Notice** (verify scope)
+4. **Return to bug-fixing context**
+
+→ Full protocol: `references/context-isolation-protocol.md`
+
+## Quick Commands
+
+```bash
+# Phase 3: Global pattern search
+grep -rn "buggy_pattern" src/
+
+# Phase 5: Lint check
+read_lints <modified_files>
+
+# RCA: Git Bisect (find regression commit)
+git bisect start && git bisect bad HEAD && git bisect good v1.0.0
+```
+
+## 🔴 AI-Assisted Debugging (AI 辅助调试)
+
+**利用 AI 工具加速 Bug 定位：**
+
+| 工具 | 用途 | 使用场景 |
+|------|------|----------|
+| Claude Code | 代码分析、错误解释 | 复杂 stack trace 解读 |
+| GitHub Copilot | 代码模式识别 | 发现类似 Bug 模式 |
+| Sentry AI | 错误聚类分析 | 生产环境问题 |
+
+**AI 辅助调试流程：**
+```
+遇到复杂错误
+       ↓
+Step 1: 将 stack trace + 相关代码发给 AI
+       ↓
+Step 2: 让 AI 解释可能的原因
+       ↓
+Step 3: 验证 AI 的假设
+       ↓
+Step 4: 如果正确 → 修复; 如果错误 → 提供更多上下文
+```
+
+**AI 提问模板：**
+```
+错误信息: [粘贴 stack trace]
+相关代码: [粘贴代码片段]
+已尝试: [列出已尝试的方法]
+问题: 这个错误的根本原因是什么？
+```
+
+## 🔴 Mandatory Post-Fix Documentation (CRITICAL)
+
+**After EVERY bug fix, you MUST update these documents:**
+
+| Document | Purpose | What to Record |
+|----------|---------|----------------|
+| `references/bug-records.md` | Project-specific bug history | Root cause + fix method |
+| `references/bug-guide.md` | Universal bug patterns | Reusable patterns for future |
+
+### Why This Is Mandatory
+
+```
+User's Real Problem:
+- bat script used dev env file
+- Bug fix only added production env config
+- Result: Bug persisted in dev mode
+
+If bug-records.md was updated:
+- Would have documented: "Fix applied to .env.production only"
+- Next developer would see: "Check all env files!"
+```
+
+### Post-Fix Documentation Checklist
+
+```markdown
+## Post-Fix Documentation (MANDATORY)
+
+### 1. bug-records.md Update
+- [ ] Added new entry with Bug ID
+- [ ] Documented root cause (1-2 sentences)
+- [ ] Documented fix method
+- [ ] Listed ALL affected files (including ALL env files)
+- [ ] Noted verification method
+
+### 2. bug-guide.md Update (if pattern is reusable)
+- [ ] Identified if this is a new pattern
+- [ ] Added pattern to appropriate category
+- [ ] Included detection method
+- [ ] Included fix template
+```
+
+### Quick Update Template
+
+```markdown
+## bug-records.md Entry
+
+| Field | Value |
+|-------|-------|
+| Bug ID | BUG-XXX |
+| Date | YYYY-MM-DD |
+| Root Cause | [Why the bug occurred] |
+| Fix Method | [How it was fixed] |
+| Affected Files | [ALL files modified, including ALL env files] |
+| Environments | [dev/staging/prod - which were affected] |
+```
+
+---
+
+## Output Contract
+
+```markdown
+## Phase -1: Knowledge Query
+- Match: [pattern name / none]
+
+## Triage
+- Entry: [UI/API/Job]
+- Classification: [Failure/Noise]
+- Severity: [P0/P1/P2]
+
+## Root Cause
+[1-sentence]
+
+## Fix Summary
+[What changed]
+
+## Skill Delegation
+| Skill | Purpose | Completed |
+|-------|---------|-----------|
+
+## Verification
+- [ ] Fix works
+- [ ] code-review passed
+- [ ] 🔴 bug-records.md updated (MANDATORY)
+- [ ] 🔴 bug-guide.md updated (if new pattern)
+- [ ] 🔴 All environments verified (dev/staging/prod)
+
+## 🔴 Post-Fix Documentation
+| Document | Updated | Notes |
+|----------|---------|-------|
+| bug-records.md | [ ] | Entry added |
+| bug-guide.md | [ ] | Pattern added (if applicable) |
+```
+
+## 🔴 代码质量检查 (Phase 4 & 5)
+
+**修复代码必须通过以下检查：**
+
+| 类别 | 检查项 | 严重等级 |
+|------|--------|----------|
+| 安全性 | SQL注入、XSS、敏感信息泄露 | **P0** |
+| 错误处理 | 异常捕获、降级策略 | **P1** |
+| 边界条件 | 空值、超时、并发 | **P1** |
+| 资源管理 | 连接释放、监听器清理 | **P1** |
+
+→ 完整清单: `../shared-references/code-quality-checklist.md`
+
+---
+
+## 🔴 MCP 依赖兼容性检查 (Phase 4 MANDATORY)
+
+**修复涉及新增依赖时，必须使用 MCP 工具验证兼容性：**
+
+| 触发条件 | MCP 工具 | 检查内容 |
+|----------|----------|----------|
+| 新增 npm/pip 包 | `context7` | 版本要求、平台兼容性 |
+| 依赖冲突疑似 | `exa` | 已知冲突、社区反馈 |
+| Electron/RN 依赖 | `exa` + `deepwiki` | 原生模块兼容性 |
+
+**快速检查流程:**
+```
+1. context7 查询: "[package] version requirements compatibility"
+2. exa 查询: "[package] known issues conflicts 2024"
+3. 本地验证: npm install --dry-run / pip install --dry-run
+```
+
+→ 完整协议: `../shared-references/mcp-dependency-compatibility-protocol.md`
+
+---
+
+## 🔴 Import Integrity Check (Phase 2 & 4)
+
+**导入错误是常见 Bug 根因，必须优先排查：**
+
+| 阶段 | 检查项 | 动作 |
+|------|--------|------|
+| Phase 2 RCA | 错误信息含 `import`/`module`/`export` | 优先排查导入问题 |
+| Phase 4 Fix | 修复涉及新增/修改 import | 校验路径+环境+副作用 |
+
+**常见导入 Bug 模式**:
+- `does not provide an export named` → 导入语法不匹配
+- `Cannot find module` → 路径错误/依赖未安装
+- `window is not defined` → Node.js 模块在浏览器中导入
+
+→ 完整协议: `../shared-references/import-integrity-protocol.md`
+
+---
+
+## 🔴 Native Module Bugs (Electron/React Native)
+
+**原生模块是 Desktop App 启动失败的头号杀手！**
+
+| 错误信息 | 根因 | 解决方案 |
+|----------|------|----------|
+| `Cannot find module 'xxx'` (Electron) | 原生模块未针对 Electron 编译 | 使用纯 JS 替代 |
+| `NODE_MODULE_VERSION mismatch` | Node ABI 版本不匹配 | electron-rebuild |
+| `was compiled against a different Node.js version` | 编译版本不匹配 | 重新编译或换纯 JS |
+
+**原生模块 → 纯 JS 替代方案**:
+
+| 原生模块 | 纯 JS 替代 | 用途 |
+|----------|-----------|------|
+| `better-sqlite3` | `sql.js` | SQLite |
+| `sqlite3` | `sql.js` | SQLite |
+| `sharp` | `jimp` | 图片处理 |
+| `bcrypt` | `bcryptjs` | 密码哈希 |
+
+**修复流程**:
+1. 识别问题依赖是否为原生模块
+2. 搜索纯 JS 替代方案
+3. 替换依赖并更新代码
+4. 🔴 运行 `npm run dev` 验证
+
+→ 详细协议: `references/dependency-and-integrity-protocol.md`
+
+---
+
+## Reference Navigation
+
+| Situation | Read This |
+|-----------|-----------|
+| 🔴 **技能编排协议** | `../shared-references/skill-orchestration-protocol.md` |
+| 🔴 **高级调试技术** | `../shared-references/advanced-debugging-techniques.md` |
+| 🔴 **MCP 依赖兼容性检查** | `../shared-references/mcp-dependency-compatibility-protocol.md` |
+| 🔴 **代码质量检查清单** | `../shared-references/code-quality-checklist.md` |
+| 🔴 **Import integrity** | `../shared-references/import-integrity-protocol.md` |
+| 🔴 **Native module bugs (Electron)** | `references/dependency-and-integrity-protocol.md` |
+| 🔴 **Complete workflow** | `references/complete-workflow.md` |
+| 🔴 **Context isolation** | `references/context-isolation-protocol.md` |
+| 🔴 **Skill delegation** | `references/skill-delegation-guide.md` |
+| 🔴 **Knowledge extraction** | `references/knowledge-extraction-guide.md` |
+| Fix completeness | `references/fix-completeness-checklist.md` |
+| Dependency gate | `references/dependency-and-integrity-protocol.md` |
+| Investigation | `references/investigation-checklist.md` |
+| Zero-regression | `references/zero-regression-matrix.md` |
+| RCA techniques | `references/rca-guide.md` |
+| Bug patterns | `references/bug-guide.md` |
+| Frontend bugs | `references/frontend-guide.md` |
+| Backend bugs | `references/backend-guide.md` |
+| Critical/Prod | `references/zero-risk-protocol.md` |