@tinkcarlos/skillora 0.2.0

package/.claude/skills/code-review/references/job-review.md

@@ -0,0 +1,335 @@
+# Job & Scheduler Review Guide
+
+> Comprehensive guide for reviewing background jobs, schedulers, cron tasks, workers, and queues.
+
+## Table of Contents
+
+- [Job Types Overview](#job-types-overview)
+- [Common Job Bugs](#common-job-bugs)
+- [Cron Expression Review](#cron-expression-review)
+- [Error Handling Patterns](#error-handling-patterns)
+- [Idempotency & Reliability](#idempotency--reliability)
+- [Performance & Scaling](#performance--scaling)
+- [Monitoring & Observability](#monitoring--observability)
+
+---
+
+## Job Types Overview
+
+| Type | Examples | Key Concerns |
+|------|----------|--------------|
+| **Cron Jobs** | Daily reports, cleanup tasks | Timing, overlap, timezone |
+| **Queue Workers** | Celery, Sidekiq, Bull, RQ | Retry, dead letter, scaling |
+| **Event Handlers** | Webhooks, message consumers | Ordering, deduplication |
+| **Scheduled Tasks** | @Scheduled, APScheduler | Memory leaks, overlap |
+| **Batch Processors** | Data migrations, ETL | Progress, resume, timeout |
+
+---
+
+## Common Job Bugs
+
+### 1. Overlapping Execution (Most Dangerous)
+
+```python
+# 🔴 BUG: Job can run twice simultaneously
+@app.task
+def daily_report():
+    # If previous run takes > 24 hours, two instances run
+    generate_large_report()
+
+# ✅ FIX: Use distributed lock
+@app.task
+def daily_report():
+    lock = redis.lock("daily_report_lock", timeout=3600)
+    if lock.acquire(blocking=False):
+        try:
+            generate_large_report()
+        finally:
+            lock.release()
+    else:
+        logger.info("Job already running, skipping")
+```
+
+### 2. Silent Failures
+
+```python
+# 🔴 BUG: Exceptions swallowed, no alerts
+@app.task
+def process_payment(payment_id):
+    try:
+        charge_customer(payment_id)
+    except Exception as e:
+        print(f"Error: {e}")  # Nobody will see this
+
+# ✅ FIX: Proper error handling with alerting
+@app.task(bind=True, max_retries=3)
+def process_payment(self, payment_id):
+    try:
+        charge_customer(payment_id)
+    except TransientError as e:
+        raise self.retry(exc=e, countdown=60)
+    except Exception as e:
+        logger.exception(f"Payment {payment_id} failed permanently")
+        alert_team(f"Payment failure: {payment_id}")
+        raise
+```
+
+### 3. Missing Timeout
+
+```python
+# 🔴 BUG: Job can run forever
+@app.task
+def call_external_api():
+    response = requests.get(url)  # No timeout!
+    process(response)
+
+# ✅ FIX: Always set timeouts
+@app.task(soft_time_limit=300, time_limit=600)
+def call_external_api():
+    response = requests.get(url, timeout=30)
+    process(response)
+```
+
+### 4. Memory Leaks in Long-Running Jobs
+
+```python
+# 🔴 BUG: Loading entire dataset into memory
+@app.task
+def export_all_users():
+    users = User.objects.all()  # 10 million users = OOM
+    for user in users:
+        export(user)
+
+# ✅ FIX: Stream with pagination
+@app.task
+def export_all_users():
+    batch_size = 1000
+    offset = 0
+    while True:
+        users = User.objects.all()[offset:offset + batch_size]
+        if not users:
+            break
+        for user in users:
+            export(user)
+        offset += batch_size
+        gc.collect()  # Force garbage collection
+```
+
+### 5. Timezone Issues
+
+```python
+# 🔴 BUG: Hardcoded timezone or using local time
+schedule.every().day.at("09:00").do(job)  # What timezone?
+
+# ✅ FIX: Explicit UTC timezone
+from celery.schedules import crontab
+app.conf.beat_schedule = {
+    'daily-report': {
+        'task': 'tasks.daily_report',
+        'schedule': crontab(hour=9, minute=0),  # UTC
+    },
+}
+app.conf.timezone = 'UTC'
+```
+
+### 6. No Idempotency
+
+```python
+# 🔴 BUG: Retry creates duplicates
+@app.task(max_retries=3)
+def send_email(user_id):
+    user = User.get(user_id)
+    send_welcome_email(user)  # Retry = duplicate email
+
+# ✅ FIX: Idempotency key
+@app.task(max_retries=3)
+def send_email(user_id, idempotency_key):
+    if redis.get(f"email_sent:{idempotency_key}"):
+        return  # Already sent
+    user = User.get(user_id)
+    send_welcome_email(user)
+    redis.set(f"email_sent:{idempotency_key}", 1, ex=86400)
+```
+
+---
+
+## Cron Expression Review
+
+### Common Cron Mistakes
+
+| Expression | Intended | Actual | Problem |
+|------------|----------|--------|---------|
+| `0 0 * * 0` | Weekly on Sunday | Wrong in some systems | Day 0 vs 7 confusion |
+| `0 9 * * *` | 9 AM daily | 9 AM in what timezone? | Timezone ambiguity |
+| `*/5 * * * *` | Every 5 minutes | Correct | - |
+| `0 */2 * * *` | Every 2 hours | Only at :00 | Missing odd hours |
+| `0 0 1 * *` | First of month | Correct | - |
+| `0 0 31 * *` | 31st of month | Skips Feb, Apr, Jun... | Not all months have 31 |
+
+### Cron Validation Commands
+
+```bash
+# Validate cron expression (requires crontab package)
+echo "0 9 * * *" | crontab -
+
+# Use online validator or library
+# Python: croniter
+# Node: cron-parser
+```
+
+### Timezone Checklist
+
+- [ ] All schedules specify timezone explicitly
+- [ ] Server timezone documented
+- [ ] DST transitions handled (or schedules avoid DST hours)
+- [ ] UTC preferred for backend jobs
+
+---
+
+## Error Handling Patterns
+
+### Retry Strategy Matrix
+
+| Error Type | Retry? | Strategy | Example |
+|------------|--------|----------|---------|
+| **Network Timeout** | Yes | Exponential backoff | `2^n` seconds |
+| **Rate Limit (429)** | Yes | Respect Retry-After header | Wait as told |
+| **Server Error (5xx)** | Yes | Limited retries | Max 3-5 times |
+| **Client Error (4xx)** | No | Fix and redeploy | Bad request |
+| **Business Logic** | No | Alert and investigate | Invalid data |
+| **Resource Exhausted** | Maybe | With cooldown | Memory/CPU |
+
+### Dead Letter Queue Pattern
+
+```python
+# ✅ GOOD: Capture failed jobs for analysis
+@app.task(bind=True, max_retries=3)
+def process_order(self, order_id):
+    try:
+        do_work(order_id)
+    except Exception as e:
+        if self.request.retries >= self.max_retries:
+            # Move to dead letter queue
+            dead_letter_queue.put({
+                'task': 'process_order',
+                'args': [order_id],
+                'error': str(e),
+                'traceback': traceback.format_exc(),
+                'timestamp': datetime.utcnow().isoformat()
+            })
+            raise
+        raise self.retry(exc=e)
+```
+
+---
+
+## Idempotency & Reliability
+
+### Idempotency Patterns
+
+| Pattern | Use Case | Implementation |
+|---------|----------|----------------|
+| **Idempotency Key** | API-triggered jobs | Store key in Redis/DB |
+| **State Machine** | Multi-step workflows | Check current state |
+| **Version/ETag** | Data updates | Compare before write |
+| **Timestamp** | Time-based jobs | Check last run time |
+
+### At-Least-Once vs Exactly-Once
+
+```python
+# At-least-once (default): Jobs may run multiple times
+# - Simpler to implement
+# - Requires idempotent handlers
+
+# Exactly-once (hard): Jobs run exactly once
+# - Requires distributed transactions
+# - Often unnecessary if idempotent
+```
+
+---
+
+## Performance & Scaling
+
+### Batch Processing Best Practices
+
+| Practice | Bad | Good |
+|----------|-----|------|
+| **Data loading** | Load all at once | Stream/paginate |
+| **Processing** | One at a time | Batch operations |
+| **Memory** | Hold in memory | Process and release |
+| **Progress** | No tracking | Checkpoint progress |
+| **Resumability** | Start from beginning | Resume from checkpoint |
+
+### Worker Scaling Checklist
+
+- [ ] Jobs are stateless
+- [ ] No shared mutable state
+- [ ] Database can handle concurrent connections
+- [ ] External APIs can handle rate
+- [ ] Monitoring for worker count
+
+---
+
+## Monitoring & Observability
+
+### Essential Metrics
+
+| Metric | Why | Alert Threshold |
+|--------|-----|-----------------|
+| **Job Duration** | Detect slowdowns | > 2x normal |
+| **Queue Depth** | Backlog growing | > N pending |
+| **Failure Rate** | Reliability | > 5% failures |
+| **Retry Rate** | Transient issues | > 10% retries |
+| **Memory Usage** | Leak detection | > 80% limit |
+
+### Logging Best Practices
+
+```python
+# ✅ GOOD: Structured logging with context
+@app.task(bind=True)
+def process_order(self, order_id):
+    logger.info("Starting order processing", extra={
+        "task_id": self.request.id,
+        "order_id": order_id,
+        "retry": self.request.retries
+    })
+    
+    # ... processing ...
+    
+    logger.info("Order processed", extra={
+        "task_id": self.request.id,
+        "order_id": order_id,
+        "duration_ms": elapsed
+    })
+```
+
+### Review Checklist
+
+```markdown
+## Job Review Checklist
+
+### Reliability
+- [ ] Job has timeout configured
+- [ ] Retry policy defined with limits
+- [ ] Dead letter handling for permanent failures
+- [ ] Idempotency implemented
+
+### Performance
+- [ ] No memory leaks (streaming for large data)
+- [ ] Batch processing where applicable
+- [ ] Appropriate concurrency limits
+- [ ] Progress tracking for long jobs
+
+### Monitoring
+- [ ] Structured logging with job context
+- [ ] Metrics for duration, failures, retries
+- [ ] Alerts for failures and backlogs
+- [ ] Dashboard for job health
+
+### Security
+- [ ] No secrets in job arguments
+- [ ] Input validation for job parameters
+- [ ] Principle of least privilege
+- [ ] Audit logging for sensitive operations
+```
+

package/.claude/skills/code-review/references/layered-checklist-protocol.md

@@ -0,0 +1,157 @@
+# Layered Checklist Protocol
+
+## 核心原则
+
+**检查清单按优先级分层，确保关键问题不被遗漏。**
+
+---
+
+## 四层检查模型
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Layer 0: CRITICAL (必须 100% 通过，否则 BLOCKED)            │
+│  ─────────────────────────────────────────────────────────  │
+│  安全漏洞 | 数据丢失 | 认证绕过 | 系统崩溃                   │
+└─────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────┐
+│  Layer 1: LOGIC (必须 100% 检查，P0/P1 必须修复)             │
+│  ─────────────────────────────────────────────────────────  │
+│  逻辑错误 | 边界条件 | 空值处理 | 异常路径                   │
+└─────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────┐
+│  Layer 2: QUALITY (必须检查，P2 可协商)                      │
+│  ─────────────────────────────────────────────────────────  │
+│  性能问题 | 资源泄漏 | 测试覆盖 | 可观测性                   │
+└─────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────┐
+│  Layer 3: STYLE (建议性，P3 不阻塞)                          │
+│  ─────────────────────────────────────────────────────────  │
+│  命名规范 | 代码风格 | 文档注释 | 代码组织                   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Layer 0: CRITICAL (4 项)
+
+| # | Check | Question | Severity |
+|---|-------|----------|----------|
+| C1 | **SQL Injection** | 是否有未参数化的 SQL 拼接？ | P0 |
+| C2 | **XSS/CSRF** | 是否有未转义的用户输入输出？ | P0 |
+| C3 | **Auth Bypass** | 是否有未验证的权限检查？ | P0 |
+| C4 | **Secrets Exposure** | 是否有硬编码的密钥/密码？ | P0 |
+
+**规则**: 任何 C1-C4 失败 → 立即 BLOCKED
+
+---
+
+## Layer 1: LOGIC (8 项)
+
+| # | Check | Question | Severity |
+|---|-------|----------|----------|
+| L1 | **Null/Undefined** | 所有可能为空的值是否都有检查？ | P0/P1 |
+| L2 | **Boundary** | 边界值（0, -1, MAX）是否正确处理？ | P1 |
+| L3 | **Off-by-One** | 循环/索引是否有 ±1 错误？ | P1 |
+| L4 | **Condition Logic** | if/else 条件是否覆盖所有情况？ | P0 |
+| L5 | **Exception Path** | 异常情况是否有处理？ | P1 |
+| L6 | **State Consistency** | 状态变更是否保持一致？ | P1 |
+| L7 | **Race Condition** | 并发访问是否有竞态？ | P0 |
+| L8 | **Return Value** | 所有路径是否都有正确返回？ | P1 |
+
+**规则**: L1-L8 必须逐项检查，P0/P1 必须修复
+
+---
+
+## Layer 2: QUALITY (6 项)
+
+| # | Check | Question | Severity |
+|---|-------|----------|----------|
+| Q1 | **N+1 Query** | 是否有循环内的数据库查询？ | P2 |
+| Q2 | **Resource Leak** | 连接/文件/监听器是否正确释放？ | P1 |
+| Q3 | **Memory** | 是否有大对象未释放/无限增长？ | P2 |
+| Q4 | **Test Coverage** | 关键路径是否有测试？ | P2 |
+| Q5 | **Error Message** | 错误信息是否有足够上下文？ | P2 |
+| Q6 | **Logging** | 关键操作是否有日志？ | P2 |
+
+**规则**: Q1-Q6 必须检查，P2 可协商
+
+---
+
+## Layer 3: STYLE (4 项)
+
+| # | Check | Question | Severity |
+|---|-------|----------|----------|
+| S1 | **Naming** | 变量/函数命名是否清晰？ | P3 |
+| S2 | **Format** | 代码格式是否符合规范？ | P3 |
+| S3 | **Comments** | 复杂逻辑是否有注释？ | P3 |
+| S4 | **Organization** | 代码结构是否合理？ | P3 |
+
+**规则**: S1-S4 建议性，不阻塞合并
+
+---
+
+## 检查执行顺序
+
+```
+1. 先执行 Layer 0 (CRITICAL)
+   - 任何失败 → 立即停止，报告 BLOCKED
+
+2. 再执行 Layer 1 (LOGIC)
+   - 逐项检查，记录所有发现
+   - P0/P1 必须修复
+
+3. 然后执行 Layer 2 (QUALITY)
+   - 逐项检查，记录所有发现
+   - P2 可协商
+
+4. 最后执行 Layer 3 (STYLE)
+   - 快速扫描，记录建议
+   - P3 不阻塞
+```
+
+---
+
+## Checkpoint 输出格式
+
+每个文件分析完成后，输出:
+
+```markdown
+## [CP-XXX] {filename} - Layered Checklist
+
+| Layer | Items | Passed | Failed | Skipped |
+|-------|-------|--------|--------|---------|
+| L0-Critical | 4 | 4 | 0 | 0 |
+| L1-Logic | 8 | 7 | 1 | 0 |
+| L2-Quality | 6 | 5 | 1 | 0 |
+| L3-Style | 4 | 3 | 0 | 1 |
+
+**Failed Items**:
+- L1.L4: Condition Logic - if/else 未覆盖 null 情况 (P1)
+- L2.Q1: N+1 Query - 循环内查询数据库 (P2)
+
+**Status**: ⚠️ CHANGES REQUESTED
+```
+
+---
+
+## 与 Progress Tracker 集成
+
+在 Progress Tracker 的 Checkpoint 中记录:
+
+```markdown
+### [CP-001] src/auth.ts
+
+**Layered Checklist**:
+| Layer | Pass Rate |
+|-------|-----------|
+| L0-Critical | 4/4 (100%) |
+| L1-Logic | 7/8 (87.5%) |
+| L2-Quality | 5/6 (83.3%) |
+| L3-Style | 3/4 (75%) |
+
+**Issues**: 2 (1×P1, 1×P2)
+```