@tinkcarlos/skillora 0.2.0

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

@@ -0,0 +1,329 @@
+# New Feature Review Guide
+
+> Review focus for "point injection": isolated impact, zero risk to existing functionality.
+
+## Overview
+
+New features are like adding a flower to an established garden. Review with focus on isolation, minimal coupling, and safe rollout.
+
+**Target Bug Rate**: ~0% (achievable through isolation and testing)
+
+---
+
+## Critical Review Areas
+
+### 1. Scope Isolation
+
+| Check | What to Verify | Red Flags |
+|-------|----------------|-----------|
+| **Feature boundary** | Clear entry/exit points | Touches many unrelated files |
+| **State isolation** | Own state, minimal global | Modifies shared global state |
+| **Dependencies** | Minimal, explicit | Many implicit dependencies |
+| **Side effects** | Contained, reversible | Irreversible side effects |
+
+### 2. Feature Flag Integration
+
+```markdown
+## Feature Flag Checklist
+
+### Implementation
+- [ ] Feature wrapped in flag check
+- [ ] Default is OFF (safe)
+- [ ] Flag can be toggled without deploy
+- [ ] Flag cleanup planned
+
+### Rollout Plan
+- [ ] Internal testing (1%)
+- [ ] Beta users (10%)
+- [ ] Gradual rollout (25% → 50% → 100%)
+- [ ] Rollback criteria defined
+
+### Monitoring
+- [ ] Feature-specific metrics
+- [ ] Error tracking per flag state
+- [ ] Performance comparison (on vs off)
+- [ ] User feedback collection
+```
+
+### 3. Contract Compliance
+
+| Aspect | Verification Method | Common Issues |
+|--------|---------------------|---------------|
+| **API Schema** | Compare with OpenAPI spec | Field name mismatches |
+| **Data Types** | Type checking (TypeScript) | Wrong types, missing nulls |
+| **Error Codes** | Documented error responses | Undocumented errors |
+| **Validation** | Input constraints match | Frontend/backend differ |
+
+### 4. Edge Case Coverage
+
+```markdown
+## Edge Case Checklist
+
+### Input Boundaries
+- [ ] Empty/null inputs handled
+- [ ] Maximum length inputs
+- [ ] Special characters (unicode, emoji)
+- [ ] Invalid format inputs
+
+### State Variations
+- [ ] First-time user
+- [ ] Returning user with data
+- [ ] User with no permissions
+- [ ] Admin user
+
+### Error Conditions
+- [ ] Network failure
+- [ ] Timeout
+- [ ] 4xx errors (validation, auth)
+- [ ] 5xx errors (server)
+
+### Concurrent Scenarios
+- [ ] Multiple users same resource
+- [ ] User with multiple tabs
+- [ ] Race conditions
+```
+
+---
+
+## Feature Development Workflow Review
+
+### 1. Requirements Clarity
+
+| Question | Answer Required | Red Flag |
+|----------|-----------------|----------|
+| What does it do? | Clear user story | Vague description |
+| Who uses it? | Defined user persona | "Everyone" |
+| Success criteria? | Measurable metric | No success definition |
+| Edge cases? | Documented | "We'll handle later" |
+
+### 2. Design Review
+
+```markdown
+## Feature Design Review
+
+### UI/UX (Frontend)
+- [ ] Design matches specification
+- [ ] All states designed (loading, error, empty, success)
+- [ ] Responsive design verified
+- [ ] Accessibility considered
+- [ ] Animation/interaction smooth
+
+### API Design (Backend)
+- [ ] RESTful/consistent with existing
+- [ ] Proper HTTP methods and codes
+- [ ] Request/response documented
+- [ ] Error responses defined
+- [ ] Rate limiting considered
+
+### Data Design
+- [ ] Schema changes minimal
+- [ ] Indexes planned
+- [ ] Migration reversible
+- [ ] Data access patterns optimized
+```
+
+### 3. Implementation Review
+
+```markdown
+## Feature Implementation Review
+
+### Code Quality
+- [ ] Follows existing patterns
+- [ ] DRY (no duplication)
+- [ ] SOLID principles applied
+- [ ] Type-safe (TypeScript/types)
+
+### Testing
+- [ ] Unit tests for logic
+- [ ] Integration tests for API
+- [ ] E2E tests for user flow
+- [ ] Edge cases covered
+- [ ] 100% coverage for new code
+
+### Performance
+- [ ] No N+1 queries
+- [ ] Lazy loading where appropriate
+- [ ] Bundle impact measured
+- [ ] Memory usage checked
+
+### Security
+- [ ] Input validation
+- [ ] Authorization checks
+- [ ] No sensitive data exposed
+- [ ] Audit logging for sensitive actions
+```
+
+---
+
+## Common Feature Review Issues
+
+### Scope Creep
+
+| Sign | Impact | Action |
+|------|--------|--------|
+| PR keeps growing | Delayed delivery | Cut scope, create follow-up tickets |
+| "While we're here..." changes | Increased risk | Separate PRs |
+| Unrelated refactoring | Review fatigue | Block, request split |
+
+### Integration Problems
+
+| Problem | Detection | Prevention |
+|---------|-----------|------------|
+| API mismatch | Integration test fails | Contract testing (Pact) |
+| Missing error handling | Runtime errors | Define all error states upfront |
+| State conflicts | UI bugs | State isolation review |
+| Performance impact | Slow pages | Performance budget |
+
+### A/B Testing Issues
+
+| Issue | Impact | Solution |
+|-------|--------|----------|
+| No metrics | Can't measure success | Instrument before merge |
+| Flicker effect | Poor UX | Server-side flags |
+| Inconsistent state | Bugs | Clean flag boundaries |
+
+---
+
+## Feature Isolation Patterns
+
+### Frontend Component Isolation
+
+```typescript
+// 🔴 BAD: Feature modifies global state
+function NewFeature() {
+  const globalState = useGlobalStore();
+  globalState.someUnrelatedThing = 'modified';  // Side effect!
+  return <div>...</div>;
+}
+
+// ✅ GOOD: Feature with isolated state
+function NewFeature() {
+  const [localState, setLocalState] = useState(null);
+  
+  // Only reads from global, doesn't modify
+  const userId = useGlobalStore(s => s.userId);
+  
+  return <div>...</div>;
+}
+```
+
+### Backend Service Isolation
+
+```python
+# 🔴 BAD: Feature modifies shared service
+class NewFeatureService:
+    def process(self, data):
+        # Modifies shared service state
+        shared_service.config = self.new_config
+        return shared_service.execute(data)
+
+# ✅ GOOD: Feature with explicit dependencies
+class NewFeatureService:
+    def __init__(self, config: NewFeatureConfig):
+        self.config = config
+    
+    def process(self, data, shared_service: SharedService):
+        # Uses shared service with local config
+        return shared_service.execute(data, config=self.config)
+```
+
+### Feature Flag Pattern
+
+```typescript
+// Feature flag wrapper
+function FeatureGate({ flag, children, fallback = null }) {
+  const isEnabled = useFeatureFlag(flag);
+  
+  if (!isEnabled) {
+    return fallback;
+  }
+  
+  return (
+    <ErrorBoundary fallback={<FeatureError />}>
+      {children}
+    </ErrorBoundary>
+  );
+}
+
+// Usage
+function App() {
+  return (
+    <FeatureGate flag="new-checkout-flow" fallback={<OldCheckout />}>
+      <NewCheckout />
+    </FeatureGate>
+  );
+}
+```
+
+---
+
+## Feature Review Template
+
+```markdown
+# New Feature Review
+
+## Feature Info
+- **Feature Name**: 
+- **JIRA/Ticket**: 
+- **Author**: 
+- **Reviewer**: 
+
+## Scope Assessment
+
+### Files Changed
+| File | Type | Risk |
+|------|------|------|
+| | New/Modified | Low/Medium/High |
+
+### Dependencies
+- **Adds**: 
+- **Modifies**: 
+- **None**: ✅
+
+## Checklist
+
+### Isolation
+- [ ] Feature flag implemented
+- [ ] No global state mutations
+- [ ] Rollback safe
+- [ ] Independent of other in-flight features
+
+### Quality
+- [ ] Type-safe
+- [ ] Follows patterns
+- [ ] DRY
+- [ ] Documented
+
+### Testing
+- [ ] Unit tests
+- [ ] Integration tests
+- [ ] Edge cases
+- [ ] 100% new code coverage
+
+### Contract
+- [ ] API matches spec
+- [ ] Error handling complete
+- [ ] Validation correct
+
+## Findings
+
+### 🔴 Blockers
+- 
+
+### 🟠 Should Fix
+- 
+
+### 🟡 Suggestions
+- 
+
+## Verdict
+- [ ] APPROVED
+- [ ] APPROVED with minor changes
+- [ ] CHANGES REQUESTED
+
+## Rollout Recommendation
+- [ ] Safe for immediate 100% rollout
+- [ ] Gradual rollout recommended
+- [ ] Internal testing first
+```
+

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

@@ -0,0 +1,326 @@
+# File Review Template
+
+Use this template for EVERY file in the review. Do not skip any section.
+
+---
+
+## File: `[path/to/file.ts]`
+
+### Metadata
+
+| Property | Value |
+|----------|-------|
+| **Full Path** | |
+| **File Type** | Service / Component / Hook / Utility / Type / Test / Config |
+| **Language** | TypeScript / JavaScript / Python / CSS / Other |
+| **Lines Total** | |
+| **Lines Changed** | +X / -Y |
+| **Last Modified** | |
+
+### Change Summary
+
+```diff
+// Show the diff or summary of changes
++ Added lines
+- Removed lines
+```
+
+---
+
+## Section-by-Section Analysis
+
+### Imports / Dependencies (Lines X-Y)
+
+```typescript
+// Paste ALL imports
+```
+
+| Line | Import | Used? | Issue | Action |
+|------|--------|-------|-------|--------|
+| 1 | `react` | ✅ | - | - |
+| 2 | `lodash` | ⚠️ Partial | Only `get` used | Cherry-pick |
+| 3 | `./utils` | ❌ No | Unused import | Remove |
+
+**Import Summary**:
+- Total imports: X
+- Unused imports: X
+- Heavy imports (could be lighter): X
+- Circular dependency risk: Yes/No
+
+---
+
+### Type Definitions (Lines X-Y)
+
+```typescript
+// Paste ALL type/interface definitions
+```
+
+| Type | Purpose | Issues | Suggestions |
+|------|---------|--------|-------------|
+| `UserInput` | Form input type | Missing validation | Add Zod schema |
+| `ApiResponse` | API return type | Too generic | Be more specific |
+
+**Type Analysis**:
+- [ ] All types properly exported
+- [ ] No `any` types
+- [ ] Proper optionality (`?` vs `| undefined`)
+- [ ] Readonly where appropriate
+- [ ] Consistent naming convention
+
+---
+
+### Constants / Configuration (Lines X-Y)
+
+```typescript
+// Paste constants
+```
+
+| Constant | Value | Issue | Suggestion |
+|----------|-------|-------|------------|
+| `MAX_RETRIES` | 3 | ✅ OK | - |
+| `API_URL` | `"https://..."` | 🔴 Hardcoded | Use env variable |
+
+---
+
+### Function: `functionName()` (Lines X-Y)
+
+```typescript
+// Paste COMPLETE function
+```
+
+#### Function Signature Analysis
+
+| Aspect | Current | Issue | Recommendation |
+|--------|---------|-------|----------------|
+| Name | `handleData` | Vague | `processUserRegistration` |
+| Parameters | `(data: any)` | No type | `(data: RegistrationData)` |
+| Return Type | Implicit | Missing | Add explicit return type |
+| Async | Yes | - | - |
+
+#### Line-by-Line Code Analysis
+
+| Line | Code Snippet | Analysis |
+|------|--------------|----------|
+| 45 | `const user = data.user` | ⚠️ No null check |
+| 46 | `if (user.active)` | ⚠️ Could throw if user null |
+| 47 | `await db.save(user)` | ✅ Properly awaited |
+| 48 | `logger.info('saved')` | ⚠️ No context in log |
+| 49 | `return user` | ⚠️ Returns mutable object |
+
+#### Control Flow Analysis
+
+```
+Entry
+  ↓
+Check: data exists? ──No──→ [Missing!]
+  ↓ Yes
+Check: user valid? ──No──→ [Missing!]
+  ↓ Yes
+Save to DB ──Error──→ [Caught?]
+  ↓ Success
+Return
+```
+
+**Issues**:
+- No validation at entry
+- No error handling
+- No null checks
+
+#### Edge Case Analysis
+
+| Input | Expected Behavior | Actual Behavior | Status |
+|-------|-------------------|-----------------|--------|
+| `null` | Throw error | Crashes | 🔴 |
+| `{}` | Throw error | Undefined behavior | 🔴 |
+| `{user: null}` | Throw error | Crashes | 🔴 |
+| Valid data | Process successfully | ✅ Works | ✅ |
+
+#### Security Analysis
+
+| Check | Status | Line | Notes |
+|-------|--------|------|-------|
+| Input validation | ❌ Missing | 45 | Add Zod/Yup validation |
+| SQL injection | ✅ OK | 47 | ORM parameterizes |
+| XSS | N/A | - | Not rendering HTML |
+| Auth check | ❌ Missing | - | Add permission check |
+
+#### Performance Analysis
+
+| Aspect | Status | Notes |
+|--------|--------|-------|
+| Time complexity | O(1) | Single DB operation |
+| DB queries | 1 | ✅ OK |
+| Memory | ✅ OK | No large allocations |
+| Caching | ❌ Missing | Consider caching user |
+
+#### Maintainability Analysis
+
+| Metric | Value | Threshold | Status |
+|--------|-------|-----------|--------|
+| Lines of code | 25 | <50 | ✅ |
+| Cyclomatic complexity | 3 | <10 | ✅ |
+| Nesting depth | 2 | <4 | ✅ |
+| Parameters | 1 | <5 | ✅ |
+
+#### Function Issues Summary
+
+| # | Line | Severity | Category | Issue | Fix |
+|---|------|----------|----------|-------|-----|
+| 1 | 45 | 🔴 Critical | Correctness | No null check | Add validation |
+| 2 | 45-49 | 🟠 Major | Security | No auth check | Add permission check |
+| 3 | 48 | 🟡 Minor | Maintainability | Log lacks context | Add userId to log |
+
+---
+
+### [Repeat for EVERY function in the file]
+
+---
+
+### React Component Analysis (If Applicable)
+
+#### Component: `ComponentName`
+
+```tsx
+// Paste complete component
+```
+
+#### Props Analysis
+
+| Prop | Type | Required | Default | Validation |
+|------|------|----------|---------|------------|
+| `userId` | string | Yes | - | ❌ No validation |
+| `onSave` | function | No | noop | ✅ OK |
+
+#### State Analysis
+
+| State | Type | Initial | Updates | Issues |
+|-------|------|---------|---------|--------|
+| `loading` | boolean | false | 3 places | ✅ OK |
+| `data` | User \| null | null | 1 place | ⚠️ No error state |
+
+#### Hooks Analysis
+
+| Hook | Dependencies | Issues |
+|------|--------------|--------|
+| `useEffect` L23 | `[userId]` | ✅ Correct deps |
+| `useEffect` L45 | `[]` | ⚠️ Missing `data` dep |
+| `useMemo` L67 | `[items]` | ✅ OK |
+| `useCallback` L78 | Missing | ⚠️ Should memoize |
+
+#### Render Analysis
+
+| Element | Accessibility | Issues |
+|---------|--------------|--------|
+| `<button>` L90 | ❌ No aria-label | Add label |
+| `<img>` L95 | ❌ No alt | Add alt text |
+| `<input>` L100 | ❌ No label | Add label |
+
+#### Component States
+
+| State | Handled? | UI Shown |
+|-------|----------|----------|
+| Loading | ✅ | Spinner |
+| Empty | ❌ Missing | - |
+| Error | ❌ Missing | - |
+| Success | ✅ | Data display |
+
+---
+
+### CSS / Styling Analysis (If Applicable)
+
+```css
+/* Paste relevant styles */
+```
+
+| Selector | Specificity | Issues |
+|----------|-------------|--------|
+| `.button` | 0-1-0 | ✅ OK |
+| `#header .nav a.link` | 1-2-1 | ⚠️ Too specific |
+| `div > p` | 0-0-2 | ⚠️ Fragile selector |
+
+**CSS Issues**:
+- [ ] No `!important` abuse
+- [ ] Consistent units (rem vs px)
+- [ ] Z-index values in scale
+- [ ] No magic numbers
+- [ ] Responsive breakpoints correct
+
+---
+
+## File Summary
+
+### Overall Assessment
+
+| Dimension | Score | Notes |
+|-----------|-------|-------|
+| Correctness | 🟠 6/10 | Missing null checks |
+| Security | 🔴 4/10 | No auth, no validation |
+| Performance | ✅ 8/10 | OK |
+| Maintainability | 🟡 7/10 | Good structure, naming could improve |
+| Test Coverage | ❌ 0/10 | No tests found |
+
+### All Issues (Sorted by Severity)
+
+| # | Line | Severity | Category | Issue | Suggested Fix |
+|---|------|----------|----------|-------|---------------|
+| 1 | 45 | 🚫 Blocker | Security | No input validation | Add Zod schema validation |
+| 2 | 52 | 🔴 Critical | Security | No auth check | Add requireAuth middleware |
+| 3 | 67 | 🟠 Major | Correctness | Null not handled | Add null check |
+| 4 | 48 | 🟡 Minor | Maintainability | Log lacks context | Include userId |
+| 5 | 2 | 🔵 Info | Performance | Could use lighter import | Cherry-pick from lodash |
+
+### Required Changes
+
+```typescript
+// Line 45: Add validation
++ import { z } from 'zod';
++ const schema = z.object({ user: z.object({ ... }) });
++ const validated = schema.parse(data);
+
+// Line 52: Add auth
++ if (!ctx.user.hasPermission('users:write')) {
++   throw new ForbiddenError();
++ }
+```
+
+### Test Requirements
+
+| Scenario | Test Exists? | Priority |
+|----------|--------------|----------|
+| Happy path | ❌ | High |
+| Null input | ❌ | High |
+| Invalid data | ❌ | High |
+| Unauthorized user | ❌ | High |
+| DB error | ❌ | Medium |
+
+---
+
+## Checklist Completion
+
+### This File's Checklist
+
+- [ ] All imports reviewed
+- [ ] All types reviewed
+- [ ] All functions reviewed line-by-line
+- [ ] All edge cases identified
+- [ ] Security checks completed
+- [ ] Performance analyzed
+- [ ] Maintainability assessed
+- [ ] Test coverage checked
+- [ ] Issues documented with fixes
+- [ ] Related files identified
+
+### Cross-References
+
+| Related File | Relationship | Review Status |
+|--------------|--------------|---------------|
+| `types/user.ts` | Imports types from | ⏳ Pending |
+| `api/users.ts` | Calls this service | ⏳ Pending |
+| `tests/auth.test.ts` | Tests this file | ⏳ Pending |
+
+---
+
+## Reviewer Notes
+
+[Any additional observations, questions for the author, or discussion points]
+