@tinkcarlos/skillora 0.2.0

package/.claude/skills/fullstack-developer/references/expert-guide.md

@@ -0,0 +1,214 @@
+# 20-Year Expert Development Guide
+
+> Core insight: Perfect code isn't bug-free code—it's code where bugs are fixed in <1 hour.
+
+## Development Context Matters
+
+| Context | Focus | Target Bug Rate |
+|---------|-------|-----------------|
+| **New Project** | Foundation, scalability, test infrastructure | <1% |
+| **Iteration** | Backward compatibility, regression prevention | <0.2% |
+| **New Feature** | Isolation, feature flags, minimal coupling | ~0% |
+
+---
+
+## New Project Development
+
+### Thinking Framework
+
+```
+1. Requirements → MVP definition, user journey mapping
+2. Architecture → Tech stack POC, data model, API contract
+3. Development → Agile sprints, core features first
+4. Launch → Monitoring, error tracking, performance audit
+```
+
+### Key Decisions
+
+| Decision | Frontend | Backend |
+|----------|----------|---------|
+| **Tech Stack** | POC 2-3 options, evaluate learning curve | Benchmark throughput/latency |
+| **State Management** | Simple (Zustand) vs Complex (Redux) | Cache (Redis) + Queue (Kafka) |
+| **API Contract** | Mock first, type generation | Swagger/OpenAPI spec first |
+| **Testing** | Jest + E2E (Cypress/Playwright) | Unit + Integration + Contract (Pact) |
+| **Deployment** | Vercel/Netlify + Sentry | K8s + ELK + Grafana |
+
+### Common Problems & Solutions
+
+| Problem | Prevention | Solution |
+|---------|------------|----------|
+| Requirements change | Freeze early, weekly review | Feature flags |
+| Wrong tech choice | POC before commit | Gradual migration |
+| Performance issues | Bundle analyzer, profiling | Lazy loading, caching |
+| Team style conflicts | ESLint + Prettier + Husky | Code ownership culture |
+| Test gaps | Mutation testing | E2E for critical paths |
+
+---
+
+## Version Iteration
+
+### Thinking Framework
+
+```
+1. Evaluate → Pain points (analytics), define goals
+2. Plan → Impact radius, backward compatibility
+3. Develop → Refactor core first, then extend
+4. Release → Canary rollout, A/B testing
+```
+
+### Key Principles
+
+| Principle | Frontend | Backend |
+|-----------|----------|---------|
+| **Compatibility** | Babel polyfill, caniuse | API versioning (/v1, /v2) |
+| **Regression** | Snapshot tests, visual regression | Property-based tests |
+| **Migration** | localStorage upgrade path | Zero-downtime schema change |
+| **Rollback** | Blue-green deployment | Idempotent migrations |
+| **Monitoring** | Hotjar heatmaps, Sentry | Distributed tracing (Jaeger) |
+
+### Common Problems & Solutions
+
+| Problem | Prevention | Solution |
+|---------|------------|----------|
+| Breaking old clients | Semantic versioning | Deprecation headers + gradual migration |
+| Data inconsistency | Saga pattern | Backup + rollback script |
+| State management chaos | Immutable updates | DevTools replay |
+| Deployment failures | Canary release | Container resource limits |
+| Tech debt accumulation | 20% sprint time | Strangler Fig pattern |
+
+---
+
+## New Feature Development
+
+### Thinking Framework
+
+```
+1. Scope → Atomic tasks, user stories
+2. Design → Component isolation (Storybook), stateless first
+3. Integrate → Feature flag, minimal coupling
+4. Validate → BDD tests, boundary cases
+```
+
+### Key Principles
+
+| Principle | Frontend | Backend |
+|-----------|----------|---------|
+| **Isolation** | Storybook component testing | DDD module boundaries |
+| **Coupling** | Props over global state | Circuit breaker pattern |
+| **Testing** | BDD (Cucumber), 100% new code | Contract + edge cases |
+| **Rollout** | LaunchDarkly flags | FF4J + chaos testing |
+| **Performance** | New JS <5KB | New endpoint <10% CPU |
+
+### Common Problems & Solutions
+
+| Problem | Prevention | Solution |
+|---------|------------|----------|
+| Scope creep | Strict MVP, weekly demo | Cut non-essentials early |
+| Integration conflicts | Contract testing (Pact) | Service mesh (Istio) |
+| UI inconsistency | Design system tokens | Visual regression (Percy) |
+| Concurrency bugs | Optimistic UI + rollback | Load testing (Artillery) |
+| Post-launch panic | Gradual rollout | Auto-rollback + Sentry alerts |
+
+---
+
+## Quality Engineering Practices
+
+### Testing Pyramid
+
+| Level | Coverage | Tools | Focus |
+|-------|----------|-------|-------|
+| Unit | 70-80% | Jest/Pytest | Business logic |
+| Integration | 15-20% | Supertest/httpx | API/service interaction |
+| E2E | 5-10% | Playwright/Cypress | Critical user flows |
+
+### Code Review Checklist
+
+**Frontend**:
+- [ ] Type safety (no `any`)
+- [ ] Performance (no unnecessary re-renders)
+- [ ] Accessibility (ARIA, keyboard nav)
+- [ ] Responsive design
+- [ ] Error boundaries
+
+**Backend**:
+- [ ] Input validation (schema)
+- [ ] Error handling (consistent format)
+- [ ] Security (no injection, auth check)
+- [ ] Performance (no N+1, indexes)
+- [ ] Logging (no sensitive data)
+
+### CI/CD Pipeline
+
+```yaml
+# Every commit should run:
+1. Lint (ESLint/Pylint) → 0 warnings
+2. Type check (TypeScript/mypy) → 0 errors
+3. Unit tests → 100% pass
+4. Security scan (Snyk/Bandit) → 0 high issues
+5. Build → Success
+
+# Pre-release:
+6. Integration tests
+7. E2E tests (critical paths)
+8. Performance audit (Lighthouse/k6)
+```
+
+---
+
+## Performance Targets
+
+| Metric | Frontend | Backend |
+|--------|----------|---------|
+| **Load Time** | LCP <2.5s, FID <100ms | API response <200ms |
+| **Bundle** | Initial <100KB | N/A |
+| **Throughput** | N/A | >1000 QPS |
+| **Uptime** | N/A | 99.99% |
+| **Error Rate** | Console errors = 0 | <0.1% 5xx |
+
+---
+
+## Expert Mindset
+
+### Frontend Expert
+
+> "Test is documentation. Perfect is bug fix time <1 hour."
+
+- **Prevention over repair** — Catch bugs before users
+- **UX first** — Beautiful code is useless if UX is broken
+- **Type safety** — TypeScript strict mode prevents runtime errors
+- **Component isolation** — Storybook testing before integration
+
+### Backend Expert
+
+> "Operations is development. Perfect is bug response <5 min."
+
+- **Reliability first** — 99.99% uptime is the baseline
+- **Data consistency** — ACID transactions, eventual consistency patterns
+- **Security by default** — OWASP Top 10 prevention
+- **Observable** — If you can't measure it, you can't fix it
+
+---
+
+## Quick Reference by Phase
+
+### Starting New Project?
+1. Define MVP and user journey
+2. POC tech stack (2-3 options)
+3. Design data model and API contract
+4. Setup CI/CD from day 1
+5. Target: <1% bug rate
+
+### Doing Iteration?
+1. Analyze pain points with data
+2. Calculate change impact radius
+3. Add regression tests for all changes
+4. Canary release + monitoring
+5. Target: <0.2% bug rate
+
+### Adding Feature?
+1. Break into atomic tasks
+2. Isolate with feature flag
+3. 100% test coverage on new code
+4. Gradual rollout
+5. Target: ~0% bug rate
+

package/.claude/skills/fullstack-developer/references/file-import-patterns.md

@@ -0,0 +1,114 @@
+# File Import Patterns
+
+Best practices for handling file imports (CSV, JSON, spreadsheets, etc.) to prevent common bugs.
+
+## Common File Import Bugs
+
+| Bug Category | Symptom | Root Cause | Prevention |
+|--------------|---------|------------|------------|
+| **Format mismatch** | Data displays incorrectly | Parser assumes format X, user provides format Y | Normalize at parse time |
+| **Type confusion** | Calculations fail, comparisons wrong | String vs number vs date misinterpretation | Explicit type conversion |
+| **Missing data** | Nulls, empty strings, or defaults appear | Inconsistent empty value handling | Define null strategy |
+| **Encoding issues** | Garbled characters | Wrong charset assumption | Detect/specify encoding |
+| **Structure mismatch** | Fields in wrong places | Column order or naming differences | Map columns explicitly |
+
+## Parse Phase Checklist
+
+### Column/Key Normalization
+
+```
+Before normalization:
+  "${columnName}", "Column Name", "column-name", "COLUMN_NAME"
+
+After normalization:
+  "columnName", "columnName", "columnName", "columnName"
+```
+
+- [ ] Strip wrapper syntax (template markers, quotes, brackets)
+- [ ] Normalize case (camelCase, snake_case, or as required)
+- [ ] Remove/replace special characters
+- [ ] Trim whitespace
+
+### Type Detection & Conversion
+
+| Source Type | Target Handling |
+|-------------|-----------------|
+| Number-like string | `parseInt`, `parseFloat` with NaN fallback |
+| Date-like string | Parse with explicit format, fallback to null |
+| Boolean-like | Map "true"/"false", "yes"/"no", "1"/"0" |
+| Null-like | Map empty, "null", "N/A", "-" to null |
+
+### Empty Value Strategy
+
+Define ONE strategy for the entire import:
+
+| Value | Strategy A (Null) | Strategy B (Default) | Strategy C (Skip) |
+|-------|-------------------|----------------------|-------------------|
+| Empty string | → null | → default value | → skip row |
+| Whitespace only | → null | → default value | → skip row |
+| Missing key | → null | → default value | → skip row |
+| Literal "null" | → null | → null | → skip row |
+
+## Validation Phase Checklist
+
+### Required Fields
+
+- [ ] Define which fields are required
+- [ ] Check presence AND non-empty
+- [ ] Provide clear error messages with row/column reference
+
+### Format Validation
+
+- [ ] Email: regex + reasonable length
+- [ ] Phone: digit extraction + length check
+- [ ] URL: protocol + domain check
+- [ ] Date: parse-ability + reasonable range
+- [ ] Custom: domain-specific patterns
+
+### Boundary Checks
+
+- [ ] String length limits
+- [ ] Number range (min/max)
+- [ ] Date range (not in future, not too old)
+- [ ] Array/list size limits
+
+## Integration Phase Checklist
+
+### Data Flow Verification
+
+```
+Source File → Parse → Validate → Transform → Store → Retrieve → Display
+      ↓          ↓        ↓          ↓         ↓         ↓         ↓
+   [Check]   [Check]  [Check]   [Check]   [Check]   [Check]   [Check]
+```
+
+At each stage, verify:
+- [ ] Data shape matches expectation
+- [ ] No silent data loss or corruption
+- [ ] Edge cases preserved correctly
+
+### End-to-End Testing
+
+| Test Case | Input | Expected Output |
+|-----------|-------|-----------------|
+| Happy path | Normal data | Correct import |
+| Empty file | 0 rows | Graceful handling |
+| Headers only | Headers, 0 data rows | Graceful handling |
+| Special chars | Unicode, symbols | Preserved or normalized |
+| Large values | Long strings, big numbers | Truncated or handled |
+| Mixed types | Numbers as strings | Correct conversion |
+
+## Error Handling
+
+### User-Facing Errors
+
+- Row number + column name + value + reason
+- Actionable: "Row 5, column 'email': 'not-an-email' is not a valid email format"
+- Summary: "3 errors found. Fix and re-upload."
+
+### Developer Errors
+
+- Full stack trace
+- Raw value that caused the issue
+- Parser state at failure point
+

package/.claude/skills/fullstack-developer/references/graceful-degradation-patterns.md

@@ -0,0 +1,78 @@
+# Graceful Degradation Patterns (优雅降级模式)
+
+**核心原则**：当系统受限时，功能降级但不失败，用户始终能得到响应。
+
+## 🔴 开发时必须考虑的场景
+
+### 1. 资源限制场景
+
+| 场景 | 必须实现的降级策略 |
+|------|-------------------|
+| Token/上下文超限 | 压缩上下文 → 禁用非必要功能 → 仍生成回复 |
+| 内存不足 | 分批处理 → 流式处理 → 返回部分结果 |
+| 请求超时 | 使用缓存 → 返回默认值 → 友好错误提示 |
+| 并发限制 | 队列排队 → 限流提示 → 稍后重试建议 |
+
+### 2. 边界条件场景
+
+| 场景 | 必须测试的行为 |
+|------|--------------|
+| 最小资源配置 | 8K token 模型、1GB 内存、100ms 超时 |
+| 最大数据量 | 100万条记录、10MB 文件、1000 并发 |
+| 空/异常输入 | 空字符串、null、特殊字符、超长文本 |
+
+## 降级策略模板
+
+```python
+class DegradationStrategy:
+    """每个受限场景都应有对应的降级策略"""
+    
+    PRIORITY_ORDER = [
+        "compress_input",      # 1. 压缩输入
+        "disable_features",    # 2. 禁用非必要功能
+        "use_simpler_model",   # 3. 使用更简单的实现
+        "return_partial",      # 4. 返回部分结果
+        "use_cache",           # 5. 使用缓存
+        "friendly_error",      # 6. 友好错误信息
+    ]
+    
+    @staticmethod
+    def apply(context, limit_type: str):
+        """按优先级尝试降级，确保最终有输出"""
+        for strategy in DegradationStrategy.PRIORITY_ORDER:
+            result = try_strategy(strategy, context)
+            if result.is_acceptable():
+                log_degradation(strategy, limit_type)
+                return result
+        
+        # 最后兜底：确保有输出
+        return create_fallback_response(
+            f"由于{limit_type}限制，无法完整处理请求。"
+        )
+```
+
+## 检查清单 (开发完成前必须确认)
+
+| # | 检查项 | 说明 |
+|---|-------|------|
+| 1 | **每个限制条件都有降级策略** | 不能只有 `if limit_exceeded: return` |
+| 2 | **用户始终能收到响应** | 非空回复，哪怕是友好错误 |
+| 3 | **降级有日志记录** | 方便调试和监控 |
+| 4 | **测试了边界场景** | 最小/最大资源配置 |
+| 5 | **降级策略可配置** | 不同环境可调整策略 |
+
+## Bug Prevention 新增规则
+
+| Rule | Bad Pattern | Good Pattern |
+|------|-------------|--------------|
+| 🔴 Hard limit fail | `if exceeded: return/break` | 压缩/降级 → 确保输出 |
+| 🔴 Silent exit | 循环 break 后无处理 | break 前设置状态/输出 |
+| 🔴 Empty response | 异常路径返回空 | 始终有 fallback 响应 |
+| 🔴 Single config | 只在开发环境测试 | 测试最小/最大资源场景 |
+
+## Detection Questions (开发完成前自问)
+
+1. **"如果资源只有一半，功能还能用吗？"** → 需要降级策略
+2. **"如果这个循环所有迭代都失败，用户会看到什么？"** → 需要兜底输出
+3. **"如果外部服务不可用，用户会卡住吗？"** → 需要超时和缓存
+4. **"最小配置环境能跑通吗？"** → 需要边界测试

package/.claude/skills/fullstack-developer/references/ide-lint-errors-guide.md

@@ -0,0 +1,183 @@
+# IDE Lint Errors Detection and Resolution Guide
+
+IDE red squiggly lines (lint errors) indicate code quality issues that must be resolved before code can be considered complete. This guide provides a systematic approach to detecting, categorizing, and fixing these errors during development.
+
+## Overview
+
+Red underlines in code editors represent diagnostics from language servers, linters, and type checkers. They indicate issues ranging from simple syntax errors to complex type mismatches. Addressing these proactively during development prevents bugs from accumulating.
+
+## Error Categories
+
+### 1. Syntax Errors (P0 - Must Fix Immediately)
+
+**Symptoms**: Code won't compile/parse; immediate red underlines on basic code structure.
+
+| Common Causes | Detection | Fix Approach |
+|---------------|-----------|--------------|
+| Missing semicolons, commas, colons | Parser error at specific line | Add missing punctuation |
+| Unmatched brackets/braces/parentheses | Error often at end of block | Use editor bracket matching to find pair |
+| Typos in keywords (`fucntion`, `retrun`) | "Unknown identifier" error | Correct spelling |
+| Invalid syntax constructs | "Unexpected token" error | Check language syntax rules |
+
+### 2. Type Errors (P0/P1 - Critical)
+
+**Symptoms**: Type checker reports mismatches; often shows expected vs actual types.
+
+| Common Causes | Detection | Fix Approach |
+|---------------|-----------|--------------|
+| Type mismatch in assignment | "Type X not assignable to Y" | Cast, convert, or fix source type |
+| Undefined type reference | "Cannot find type X" | Import type or define it |
+| Wrong generic parameters | "Expected N type arguments" | Check generic signature |
+| Null/undefined not handled | "Object possibly undefined" | Add null checks or assertions |
+| Incorrect function return type | "Return type mismatch" | Fix return statement or signature |
+
+### 3. Import/Module Errors (P1 - Must Fix)
+
+**Symptoms**: Imports highlighted red; "module not found" messages.
+
+| Common Causes | Detection | Fix Approach |
+|---------------|-----------|--------------|
+| Missing import statement | "X is not defined" | Add import for the symbol |
+| Wrong import path | "Cannot find module X" | Check relative/absolute path |
+| Circular dependencies | Complex error, often runtime | Refactor to break cycle |
+| Package not installed | "Cannot find module X" | Install package via package manager |
+| Wrong export/import style | "X has no default export" | Match import style to export |
+
+### 4. Linting Rule Violations (P2/P3 - Should Fix)
+
+**Symptoms**: Warnings or errors from ESLint, Pylint, Ruff, etc.
+
+| Common Causes | Detection | Fix Approach |
+|---------------|-----------|--------------|
+| Unused variables/imports | "X is defined but never used" | Remove or use the symbol |
+| Code style violations | Various formatting warnings | Auto-fix or manual adjustment |
+| Deprecated API usage | "X is deprecated" | Update to recommended API |
+| Unsafe patterns | Security/safety warnings | Refactor to safe pattern |
+| Complexity warnings | "Function too complex" | Refactor to simpler structure |
+
+### 5. Declaration Errors (P1 - Must Fix)
+
+**Symptoms**: Variables or functions highlighted as undefined.
+
+| Common Causes | Detection | Fix Approach |
+|---------------|-----------|--------------|
+| Using before declaration | "X used before defined" | Move declaration before use |
+| Missing variable declaration | "X is not defined" | Add let/const/var or import |
+| Scope issues | "X is not accessible" | Check variable scope |
+| Missing function definition | "X is not a function" | Define or import function |
+
+### 6. Configuration Issues (P1 - Must Fix)
+
+**Symptoms**: Errors not related to specific code lines; often project-wide.
+
+| Common Causes | Detection | Fix Approach |
+|---------------|-----------|--------------|
+| Missing tsconfig.json | TypeScript errors everywhere | Create/fix tsconfig.json |
+| Wrong compiler options | Unexpected type behavior | Check and fix compiler settings |
+| Missing type definitions | "Cannot find type X" for packages | Install @types/X package |
+| ESLint/Pylint misconfiguration | Inconsistent linting | Check linter config files |
+| Python virtual env issues | Import errors for installed packages | Activate correct venv |
+
+## Detection Workflow
+
+### Step 1: Run `read_lints` Tool
+
+```
+read_lints(paths: ["path/to/modified/file.ts"])
+```
+
+This returns all diagnostics (errors, warnings, hints) for the specified files.
+
+### Step 2: Categorize Errors
+
+Group errors by category using the table above:
+- **P0 (Syntax, Critical Type)**: Fix immediately, blocks execution
+- **P1 (Import, Declaration, Type, Config)**: Fix before commit
+- **P2 (Linting warnings)**: Fix or document suppression
+- **P3 (Style nits)**: Optional, follow team conventions
+
+### Step 3: Fix in Priority Order
+
+1. Fix all P0 errors first (code won't work otherwise)
+2. Fix all P1 errors (code may have runtime issues)
+3. Fix P2 errors or add justified suppressions
+4. Optionally fix P3 style issues
+
+### Step 4: Verify Resolution
+
+Run `read_lints` again to confirm:
+- No new errors introduced
+- Original errors resolved
+- No cascading issues from fixes
+
+## Resolution Strategies by Language
+
+### TypeScript/JavaScript
+
+| Error Pattern | Quick Fix |
+|---------------|-----------|
+| "Cannot find name 'X'" | Add import: `import { X } from 'module'` |
+| "Type 'X' is not assignable to 'Y'" | Check types, add cast if intentional |
+| "Object is possibly 'undefined'" | Add optional chaining `?.` or null check |
+| "Property 'X' does not exist" | Check spelling, add property to interface |
+| "Module has no exported member 'X'" | Check export name, use correct import |
+
+### Python
+
+| Error Pattern | Quick Fix |
+|---------------|-----------|
+| "Undefined name 'X'" | Add import or define variable |
+| "X is not defined" (Pylint) | Import missing module |
+| "Missing type annotation" | Add type hint: `def f(x: int) -> str:` |
+| "Incompatible types" (mypy) | Fix type mismatch or add cast |
+| "Module 'X' has no attribute 'Y'" | Check module API, fix import |
+
+### General Patterns
+
+| Error Pattern | Quick Fix |
+|---------------|-----------|
+| Unmatched brackets | Use editor bracket matching |
+| Trailing whitespace | Configure editor auto-trim |
+| Unused imports | Remove or add usage |
+| Undefined symbol | Add import or declaration |
+| Type assertion needed | Add type annotation or cast |
+
+## Integration with Development Workflow
+
+### During Implementation
+
+1. **After every file edit**: Run `read_lints` on the modified file
+2. **Before moving to next feature**: Ensure zero P0/P1 errors
+3. **At code review gate**: Zero lint errors required
+
+### Pre-Commit Checklist
+
+- [ ] Run `read_lints` on ALL modified files
+- [ ] Zero P0 errors (syntax, critical type)
+- [ ] Zero P1 errors (imports, declarations, config)
+- [ ] P2 errors fixed or documented with justification
+- [ ] No new errors introduced during fixes
+
+## Common Pitfalls
+
+| Pitfall | Why It Happens | Prevention |
+|---------|----------------|------------|
+| Fixing one error creates another | Type changes cascade | Check all usages before changing types |
+| Ignoring warnings | "It still runs" mentality | Treat warnings as errors in CI |
+| Suppressing without reason | Quick fix habit | Always document suppression reason |
+| Not checking related files | Focus on single file | Run lints on entire changed set |
+| Missing transitive dependencies | Import from imported module | Check full dependency chain |
+
+## Verification Checklist
+
+Before marking code as complete:
+
+- [ ] Run `read_lints` on ALL modified files
+- [ ] Zero P0 errors (syntax, critical type)
+- [ ] Zero P1 errors (imports, declarations, config)
+- [ ] P2 errors fixed or documented with justification
+- [ ] No new errors introduced during fixes
+- [ ] Related files also checked (imports may cascade)
+
+→ Return to main workflow: Post-Development Protocol
+