@tinkcarlos/skillora 0.2.0

package/.claude/skills/code-review/references/review-knowledge-workflow.md

@@ -0,0 +1,257 @@
+# Knowledge Workflow for Code Review
+
+This document describes the knowledge accumulation and utilization workflow for code review.
+
+---
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                      Knowledge Architecture                          │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                      │
+│  ┌──────────────────────┐      ┌──────────────────────┐             │
+│  │   PROJECT LEVEL      │      │     SKILL LEVEL      │             │
+│  │   (Project-specific) │      │  (Cross-project)     │             │
+│  ├──────────────────────┤      ├──────────────────────┤             │
+│  │                      │      │                      │             │
+│  │  code-review-        │ ──►  │  review-guide.md     │             │
+│  │  record.md           │      │  ────────────────    │             │
+│  │  ────────────────    │      │  • Pattern library   │             │
+│  │  • Specific findings │      │  • Detection methods │             │
+│  │  • Actual code refs  │      │  • Recommendations   │             │
+│  │  • Real resolutions  │      │  • Priority matrix   │             │
+│  │                      │      │                      │             │
+│  └──────────────────────┘      └──────────────────────┘             │
+│         ▲                              │                            │
+│         │                              │                            │
+│         │  Record                      │  Reference                 │
+│         │                              ▼                            │
+│  ┌──────────────────────────────────────────────────────────────┐  │
+│  │                     CODE REVIEW PROCESS                       │  │
+│  └──────────────────────────────────────────────────────────────┘  │
+│                                                                      │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Phase 0.5: Knowledge Check (Before Detailed Review)
+
+**Purpose**: Leverage historical findings and known patterns to focus review efforts.
+
+### Step 1: Check Project History
+
+```markdown
+1. Look for code-review-record.md in project root
+2. If exists, search for:
+   - Issues in same module/component being reviewed
+   - Recent P0/P1 findings that may recur
+   - Patterns specific to this codebase
+3. Note any high-frequency issues for focused checking
+```
+
+### Step 2: Review Universal Patterns
+
+```markdown
+1. Read references/review-guide.md
+2. Note patterns relevant to this change type:
+   - Security changes → Check security patterns
+   - Async code → Check concurrency patterns
+   - API changes → Check contract patterns
+3. Add relevant patterns to your review checklist
+```
+
+### Step 3: Document in Review Plan
+
+Add to your review plan:
+
+```markdown
+## Knowledge Check
+- Project code-review-record.md: [Found/Not found]
+- High-frequency issues in this area: [List or None]
+- Applicable patterns from review-guide.md: [Pattern names]
+- Focus areas based on history: [List]
+```
+
+---
+
+## Phase 8: Knowledge Update (After Report)
+
+**Purpose**: Record significant findings for future reference and pattern extraction.
+
+### 🔴 Step 0: Check for Existing File (MANDATORY)
+
+**Before creating any file:**
+1. Check if `code-review-record.md` exists in project root
+2. If YES → Read it, find the last REV-NNN ID, and append
+3. If NO → Create using template from `references/review-record-template.md`
+
+**NEVER create versioned files like `CODE_REVIEW_REPORT_V1.md`!**
+
+### Step 1: Add Record to Project code-review-record.md
+
+Only record if there are P0/P1 findings worth remembering.
+
+If code-review-record.md doesn't exist, create it using the template from `references/review-record-template.md`.
+
+Add a new entry with:
+- Review ID (sequential, based on last ID in file)
+- Date, scope, verdict
+- Findings summary table
+- P0/P1 finding details
+- Lessons learned
+
+**Entry placement**: Add new entries at the TOP of the file (most recent first).
+
+### Step 2: What to Record
+
+| Record | Skip |
+|--------|------|
+| P0/P1 findings with details | P3 style nits |
+| Recurring patterns | One-time typos |
+| Security issues | Already-known patterns |
+| Breaking changes | Personal preferences |
+| First occurrence of new pattern | Obvious fixes |
+
+### Step 3: Extract Patterns (Periodic)
+
+After every 5-10 review records:
+
+```markdown
+1. Review recent findings for common themes
+2. Abstract project-specific details to universal patterns
+3. Update references/review-guide.md with new patterns
+4. Update review checklist if needed
+```
+
+---
+
+## Record Format Reference
+
+### Minimal Record (Few Findings)
+
+```markdown
+## [REV-NNN] Brief Title
+
+**Date**: YYYY-MM-DD | **Verdict**: APPROVED WITH COMMENTS
+
+**Findings**: 
+| Sev | Category | Issue | Status |
+|-----|----------|-------|--------|
+| P1 | Security | Missing rate limit | Fixed |
+
+**Lesson**: Always check rate limiting on auth endpoints.
+```
+
+### Full Record (Significant Review)
+
+Use the complete template from `references/review-record-template.md`.
+
+---
+
+## Pattern Abstraction Rules
+
+When extracting patterns for review-guide.md, follow these rules:
+
+### What to Remove (Project-Specific)
+
+- Actual file paths (`/src/controllers/UserController.ts`)
+- Specific function/class names (`handleUserLogin`)
+- Exact line numbers (`line 45`)
+- Specific API endpoints (`POST /api/users/login`)
+- Concrete error messages (`TypeError: Cannot read 'id'`)
+
+### What to Keep (Universal)
+
+- Issue category (security, performance, error handling)
+- Finding type (missing check, wrong handling, etc.)
+- Detection method (search for X, check Y)
+- Recommendation (add Z, use pattern W)
+
+### Abstraction Examples
+
+| Project-Specific | Universal |
+|------------------|-----------|
+| "UserController.login missing rate limit" | "Auth endpoint without rate limiting" |
+| "useEffect in ChatPanel missing cleanup" | "useEffect missing cleanup function for subscriptions" |
+| "getUser() returns null but caller doesn't check" | "Nullable return value not checked by caller" |
+
+---
+
+## Integration with Output Contract
+
+Add to your review report:
+
+```markdown
+## Knowledge Update
+
+### Project Record
+- Added to: code-review-record.md
+- Review ID: REV-NNN
+- Findings recorded: [N] P0/P1
+
+### Pattern Extraction
+- New pattern identified: [Yes/No]
+- Pattern name: [If yes]
+- Added to review-guide.md: [Yes/No]
+
+### Related Findings
+- Similar past findings: [REV-XXX-F1, REV-YYY-F2] or [None]
+- Recurring pattern confirmed: [Yes/No]
+```
+
+---
+
+## Workflow Checklist
+
+### Before Starting Review
+
+- [ ] Checked project code-review-record.md for history
+- [ ] Reviewed review-guide.md for relevant patterns
+- [ ] Noted high-frequency issues in this area
+- [ ] Added historical patterns to review checklist
+
+### After Completing Review
+
+- [ ] Added P0/P1 findings to project code-review-record.md
+- [ ] Linked related findings if pattern repeats
+- [ ] Considered if pattern should be extracted
+- [ ] Updated review-guide.md if new pattern found
+
+### Periodic Maintenance (Every 5-10 Reviews)
+
+- [ ] Reviewed recent finding records
+- [ ] Identified recurring themes
+- [ ] Abstracted to universal patterns
+- [ ] Updated review-guide.md pattern library
+- [ ] Updated review checklist if needed
+- [ ] Discussed recurring issues with team
+
+---
+
+## Quick Decisions
+
+### Should I Record This Finding?
+
+```
+P0 (Critical)?         → Yes, full details
+P1 (High)?             → Yes, with context
+P2 (Medium)?           → Table only, no details
+P3 (Low)?              → Skip unless pattern-forming
+Already in guide?      → Skip, just link
+First occurrence?      → Record for tracking
+```
+
+### Should I Extract a Pattern?
+
+```
+Same issue 3+ times?   → Yes, extract now
+Same category repeat?  → Yes, extract pattern
+Security/data issue?   → Yes, even if first time
+Style preference?      → No
+One-time mistake?      → No
+Already in guide?      → No, just link
+```
+

package/.claude/skills/code-review/references/review-progress-tracker-protocol.md

@@ -0,0 +1,172 @@
+# Review Progress Tracker Protocol
+
+## 核心原则
+
+**每次 code review 必须生成并维护一个进度追踪文档，确保：**
+1. 每个文件都被分析
+2. 每个检查项都被执行
+3. 所有发现都有记录
+
+---
+
+## 进度追踪文档格式
+
+### 文件位置
+
+```
+项目根目录/.review/
+├── review-session-{timestamp}.md  # 当前 review 会话
+└── archive/                       # 历史 review 记录
+```
+
+### 文档结构
+
+```markdown
+# Code Review Progress Tracker
+
+## Session Info
+- **Session ID**: REV-{YYYYMMDD}-{HHmm}
+- **Reviewer**: AI Assistant
+- **Start Time**: {timestamp}
+- **Status**: 🔄 In Progress / ✅ Completed
+
+---
+
+## 1. File Analysis Progress
+
+| # | File | Status | Issues | Checkpoint |
+|---|------|--------|--------|------------|
+| 1 | src/auth.ts | ✅ Done | 3 | [CP-001] |
+| 2 | src/api.ts | 🔄 In Progress | - | - |
+| 3 | src/utils.ts | ⏳ Pending | - | - |
+
+**Progress**: 1/3 files (33%)
+
+---
+
+## 2. Checkpoints (Evidence of Analysis)
+
+### [CP-001] src/auth.ts
+- **Analyzed At**: {timestamp}
+- **Functions Analyzed**: 5/5
+- **Branches Traced**: 12
+- **Return Paths Verified**: 8
+
+**Checklist Completion**:
+| Layer | Items | Passed | Failed |
+|-------|-------|--------|--------|
+| L0-Critical | 4 | 3 | 1 |
+| L1-Logic | 5 | 5 | 0 |
+| L2-Quality | 4 | 4 | 0 |
+| L3-Style | 4 | 4 | 0 |
+
+---
+
+## 3. Findings Registry
+
+### P0 (Must-Fix)
+| ID | File:Line | Issue | Evidence |
+|----|-----------|-------|----------|
+| BUG-001 | auth.ts:45 | SQL Injection | `query = f"SELECT * FROM users WHERE id = {user_id}"` |
+
+### P1 (Should-Fix)
+| ID | File:Line | Issue | Evidence |
+|----|-----------|-------|----------|
+| BUG-002 | auth.ts:78 | Null not handled | `user.name.toLowerCase()` without null check |
+
+### P2-P3 (Minor)
+...
+
+---
+
+## 4. Cross-Reference Analysis
+
+### Call Chain Traced
+| Symbol | Defined In | Called By | Depth |
+|--------|------------|-----------|-------|
+| `validateUser()` | auth.ts:10 | api.ts:25, login.ts:30 | 2 |
+| `hashPassword()` | auth.ts:50 | validateUser() | 1 |
+
+---
+
+## 5. Review Summary
+
+- **Total Files**: 3
+- **Files Analyzed**: 3/3 (100%)
+- **Total Issues**: 5
+  - P0: 1
+  - P1: 2
+  - P2: 1
+  - P3: 1
+- **Verdict**: CHANGES REQUESTED
+```
+
+---
+
+## 强制规则
+
+### Rule 1: 必须先创建 Tracker
+
+```
+开始 review 前:
+1. 创建 .review/ 目录（如不存在）
+2. 创建 review-session-{timestamp}.md
+3. 列出所有待审查文件
+```
+
+### Rule 2: 每个文件必须有 Checkpoint
+
+```
+分析完一个文件后，必须输出:
+
+## [CP-XXX] {filename}
+- Analyzed At: {timestamp}
+- Functions: X/X
+- Branches: X
+- Return Paths: X
+- Issues Found: X
+```
+
+### Rule 3: 发现必须有证据
+
+```
+每个 bug 必须包含:
+- File:Line
+- Code snippet (3-5 lines context)
+- Issue description
+- Impact analysis
+```
+
+### Rule 4: 完成前必须验证覆盖率
+
+```
+Review 结束前检查:
+- [ ] 所有文件状态为 ✅ Done
+- [ ] 所有 Checkpoint 已记录
+- [ ] Progress = 100%
+```
+
+---
+
+## 与 SKILL.md 的集成
+
+在 SKILL.md 的 Phase A 中添加:
+
+```markdown
+### Phase A: 创建 Progress Tracker (FIRST!)
+
+1. 创建 `.review/review-session-{timestamp}.md`
+2. 列出所有待审查文件
+3. 设置初始状态为 ⏳ Pending
+```
+
+在 Phase D 中添加:
+
+```markdown
+### Phase D: Checkpoint 输出 (MANDATORY)
+
+每个文件分析完成后，必须:
+1. 更新 Progress Tracker 中的文件状态
+2. 输出 Checkpoint 确认
+3. 记录发现的问题
+```

package/.claude/skills/code-review/references/review-record-template.md

@@ -0,0 +1,195 @@
+# Code Review Record Template (code-review-record.md)
+
+This template defines the standard format for project-level code review records. Create `code-review-record.md` in your project root directory using this structure.
+
+## 🔴 Single Document Rule
+
+**Each project has exactly ONE `code-review-record.md` file.**
+
+- ❌ DO NOT create `CODE_REVIEW_REPORT_V1.md`, `CODE_REVIEW_REPORT_V2.md`, etc.
+- ❌ DO NOT create a new file for each review session
+- ✅ Always append to the existing `code-review-record.md`
+- ✅ Check for existing file before creating new one
+
+## File Header
+
+```markdown
+# Code Review Record
+
+This document tracks issues found during code reviews to prevent recurrence and enable pattern extraction.
+
+Last Updated: [YYYY-MM-DD]
+Total Records: [N]
+```
+
+## Record Entry Format
+
+Each review session should document significant findings using this structure:
+
+```markdown
+---
+
+## [REV-NNN] Review Title / PR Reference
+
+**Date**: YYYY-MM-DD
+**Reviewer**: [Name/Role]
+**Scope**: [Files/modules reviewed]
+**Verdict**: APPROVED | APPROVED WITH COMMENTS | CHANGES REQUESTED | BLOCKED
+
+### Findings Summary
+
+| ID | Severity | Category | Description | Status |
+|----|----------|----------|-------------|--------|
+| F1 | P0 | [Category] | Brief description | Fixed/Deferred |
+| F2 | P1 | [Category] | Brief description | Fixed |
+| ... | ... | ... | ... | ... |
+
+### P0/P1 Finding Details
+
+#### F1: [Finding Title]
+
+**Category**: [See categories below]
+**Location**: [file:line or module/component]
+**Severity**: P0 | P1
+
+**Issue**:
+- What was found (specific)
+- Why it's a problem
+
+**Root Cause**:
+- Why this issue exists (knowledge gap, oversight, complexity)
+
+**Resolution**:
+- How it was fixed
+- Or why it was deferred
+
+**Pattern Notes**:
+- Is this a recurring pattern?
+- Related findings: [REV-XXX-F1, REV-YYY-F2]
+- Prevention suggestion
+
+### Lessons Learned
+
+- Key takeaway 1
+- Key takeaway 2
+
+---
+```
+
+## Finding Categories
+
+| Category | Description |
+|----------|-------------|
+| **Correctness** | Logic errors, boundary conditions, off-by-one |
+| **Error Handling** | Missing/wrong error handling, swallowed exceptions |
+| **Security** | Auth bypass, injection, data exposure |
+| **Performance** | N+1 queries, inefficient algorithms, memory leaks |
+| **Concurrency** | Race conditions, deadlocks, async issues |
+| **Data Integrity** | Missing validation, inconsistent state |
+| **API Contract** | Breaking changes, missing fields, wrong types |
+| **Resource Management** | Leaks, missing cleanup, unclosed connections |
+| **Observability** | Missing logs, sensitive data in logs |
+| **Testing** | Missing tests, inadequate coverage |
+| **Code Quality** | Unclear intent, complexity, maintainability |
+
+## Severity Levels
+
+| Level | Meaning | Action Required |
+|-------|---------|-----------------|
+| **P0** | Critical - blocks merge | Must fix before approval |
+| **P1** | High - should fix | Should fix soon |
+| **P2** | Medium - recommended | Fix or justify deferral |
+| **P3** | Low - nice to have | Optional improvement |
+
+## Example Entry
+
+```markdown
+---
+
+## [REV-001] User Authentication Refactor
+
+**Date**: 2025-01-05
+**Reviewer**: Senior Dev
+**Scope**: auth/, middleware/, tests/auth/
+**Verdict**: CHANGES REQUESTED
+
+### Findings Summary
+
+| ID | Severity | Category | Description | Status |
+|----|----------|----------|-------------|--------|
+| F1 | P0 | Security | Missing rate limit on login endpoint | Fixed |
+| F2 | P1 | Error Handling | Token validation swallows exceptions | Fixed |
+| F3 | P2 | Testing | No tests for edge case: expired token | Deferred |
+
+### P0/P1 Finding Details
+
+#### F1: Missing Rate Limit on Login Endpoint
+
+**Category**: Security
+**Location**: auth/loginHandler.ts:45
+**Severity**: P0
+
+**Issue**:
+- Login endpoint accepts unlimited requests
+- Enables brute force attacks on user passwords
+
+**Root Cause**:
+- Rate limiting was assumed to be handled by infrastructure layer
+- No explicit check in code review checklist
+
+**Resolution**:
+- Added express-rate-limit middleware
+- Configured: 5 attempts per 15 minutes per IP
+
+**Pattern Notes**:
+- Recurring pattern: No (first occurrence)
+- Prevention: Add rate limiting to security review checklist
+
+#### F2: Token Validation Swallows Exceptions
+
+**Category**: Error Handling
+**Location**: auth/tokenValidator.ts:23
+**Severity**: P1
+
+**Issue**:
+- Catch block returns null without logging
+- Makes debugging auth failures very difficult
+
+**Root Cause**:
+- Developer wanted to simplify error handling
+- Didn't consider observability implications
+
+**Resolution**:
+- Added structured logging before return
+- Error includes token prefix for tracing (not full token)
+
+**Pattern Notes**:
+- Recurring pattern: Yes - similar to REV-003-F2
+- Prevention: Add "no silent catch" to code review checklist
+
+### Lessons Learned
+
+- Always verify security controls are in place, not assumed
+- Silent error handling creates debugging nightmares
+
+---
+```
+
+## Maintenance Guidelines
+
+1. **Add new entries at the top** (most recent first)
+2. **Only record P0/P1 details** - P2/P3 can be summarized in table
+3. **Link related findings** to track recurring patterns
+4. **Review periodically** to extract common patterns for `review-guide.md`
+5. **Keep entries actionable** - focus on prevention, not blame
+
+## Quick Reference: What to Record
+
+| Always Record | Sometimes Record | Don't Record |
+|---------------|------------------|--------------|
+| P0/P1 findings with details | P2 findings (table only) | P3 style nits |
+| Security issues | Performance concerns | Personal preferences |
+| Breaking changes | Testing gaps | Already-known patterns |
+| Data integrity risks | Observability gaps | Obvious fixes |
+| Pattern-forming issues | First occurrences | One-time typos |
+