@tinkcarlos/skillora 0.2.0

package/.claude/skills/product-requirements/references/workflow-templates.md

@@ -0,0 +1,266 @@
+# Requirement Analysis Workflow Templates
+
+This document contains detailed templates for each phase of the requirement analysis workflow. Use these templates when executing the corresponding phases.
+
+---
+
+## Phase 2: User Persona Template
+
+Define at least 2-3 user personas using this template:
+
+```markdown
+## User Persona: [Name]
+
+**Demographics**
+- Age range: 
+- Tech proficiency: Beginner / Intermediate / Advanced
+- Device preference: Mobile / Desktop / Both
+- Usage frequency: Daily / Weekly / Monthly
+
+**Goals**
+- Primary goal: 
+- Secondary goals:
+
+**Pain Points**
+- Current frustrations:
+- What they've tried:
+
+**Behaviors**
+- How they currently solve this problem:
+- Key workflows:
+
+**Quotes** (Representative voice)
+- "I wish I could..."
+- "It's frustrating when..."
+```
+
+---
+
+## Phase 3: User Story Mapping Template
+
+Create comprehensive user story map:
+
+```markdown
+## User Story Map
+
+### Epic: [Feature Name]
+
+#### User Journey Phases
+1. [Discovery] -> 2. [Onboarding] -> 3. [Core Action] -> 4. [Completion] -> 5. [Return]
+
+#### Stories by Phase
+
+**Phase 1: Discovery**
+| Story ID | As a... | I want to... | So that... | Priority |
+|----------|---------|--------------|------------|----------|
+| US-001 | new user | see feature benefits | I understand its value | Must |
+| US-002 | returning user | quickly access feature | I save time | Must |
+
+**Phase 2: Core Action**
+| Story ID | As a... | I want to... | So that... | Priority |
+|----------|---------|--------------|------------|----------|
+| US-010 | ... | ... | ... | ... |
+```
+
+**Priority Legend (MoSCoW)**:
+- **Must** - Critical for launch
+- **Should** - Important but not blocking
+- **Could** - Nice to have
+- **Won't** - Explicitly excluded
+
+---
+
+## Phase 4: Feature Specification Template
+
+For EACH page/screen, complete this template:
+
+```markdown
+## Feature: [Feature Name]
+### Page: [Page Name]
+
+#### 1. Purpose & Context
+- **What**: What does this page do?
+- **Why**: Why does the user need this?
+- **When**: When do users access this page?
+- **Entry points**: How do users get here?
+- **Exit points**: Where do users go next?
+
+#### 2. Page Layout & Components
+
+| Component | Type | Description | Required? |
+|-----------|------|-------------|-----------|
+| Header | Navigation | Logo, nav links, user menu | Yes |
+| Hero Section | Content | Main CTA, value proposition | Yes |
+| Form | Interactive | User input fields | Yes |
+| ... | ... | ... | ... |
+
+#### 3. Component Details
+
+For EACH component:
+
+##### Component: [Name]
+- **Purpose**: Why does this exist?
+- **Visual**: Size, position, styling notes
+- **Content**: Text, images, data displayed
+- **States**: All possible states (see state matrix)
+- **Interactions**: What happens on click/hover/etc
+- **Validation**: Input rules if applicable
+- **Accessibility**: ARIA labels, keyboard nav
+
+#### 4. State Matrix
+
+| State | Trigger | Visual Change | User Action |
+|-------|---------|---------------|-------------|
+| Default | Page load | Normal appearance | Can interact |
+| Loading | Action initiated | Spinner, disabled | Wait |
+| Success | Action complete | Green feedback | Continue |
+| Error | Action failed | Red message | Retry/Fix |
+| Empty | No data | Empty state UI | Add data |
+| Disabled | No permission | Grayed out | None |
+
+#### 5. User Flow (Mermaid)
+
+```mermaid
+graph TD
+    A[Entry Point] --> B{User Action}
+    B -->|Valid| C[Process]
+    B -->|Invalid| D[Error Message]
+    C --> E{Result}
+    E -->|Success| F[Success State]
+    E -->|Failure| G[Failure State]
+```
+
+#### 6. Error Scenarios
+
+| Error Code | Scenario | User Message | Recovery Action |
+|------------|----------|--------------|-----------------|
+| E001 | Network timeout | "Connection lost. Retry?" | Retry button |
+| E002 | Invalid input | "[Field] is invalid" | Highlight field |
+| E003 | Server error | "Something went wrong" | Contact support |
+| ... | ... | ... | ... |
+
+#### 7. Acceptance Criteria (Gherkin)
+
+```gherkin
+Feature: [Feature Name]
+
+  Scenario: Successful [action]
+    Given I am on the [page]
+    And I am logged in as [user type]
+    When I [action]
+    Then I should see [expected result]
+    And [side effect] should happen
+
+  Scenario: Failed [action] due to [reason]
+    Given I am on the [page]
+    When I [action] with [invalid data]
+    Then I should see error message "[message]"
+    And the form should not be submitted
+```
+```
+
+---
+
+## Phase 5: API & Data Requirements Template
+
+```markdown
+## Data Requirements
+
+### Data Entities
+| Entity | Fields | Source | Update Frequency |
+|--------|--------|--------|-----------------|
+| User | id, name, email | Backend | On change |
+| ... | ... | ... | ... |
+
+### API Endpoints Needed
+| Method | Endpoint | Purpose | Request | Response |
+|--------|----------|---------|---------|----------|
+| GET | /api/users | List users | - | User[] |
+| POST | /api/users | Create user | UserInput | User |
+| ... | ... | ... | ... | ... |
+
+### Data Validation Rules
+| Field | Type | Required | Validation |
+|-------|------|----------|------------|
+| email | string | Yes | Valid email format |
+| password | string | Yes | Min 8 chars, 1 number, 1 special |
+| ... | ... | ... | ... |
+```
+
+---
+
+## Phase 6: Analytics & Tracking Template
+
+```markdown
+## Analytics Requirements
+
+### Key Metrics
+| Metric | Definition | Target | Tracking Event |
+|--------|------------|--------|----------------|
+| Conversion Rate | Users completing action / Total users | >5% | action_complete |
+| Time to Complete | Avg time from start to finish | <60s | action_duration |
+| Error Rate | Failed actions / Total attempts | <2% | action_error |
+
+### Event Tracking
+| Event Name | Trigger | Properties |
+|------------|---------|------------|
+| page_view | Page load | page_name, referrer |
+| button_click | Button clicked | button_id, button_text |
+| form_submit | Form submitted | form_id, success |
+| error_shown | Error displayed | error_code, error_message |
+```
+
+---
+
+## Phase 7: Non-Functional Requirements Template
+
+```markdown
+## Non-Functional Requirements
+
+### Performance
+- Page load time: <=2s on 3G
+- Time to interactive: <=3s
+- API response time: <=500ms p95
+
+### Security
+- Authentication required: Yes/No
+- Authorization levels: [List roles]
+- Data sensitivity: Public/Internal/Confidential/Restricted
+
+### Accessibility
+- WCAG level: AA
+- Screen reader support: Required
+- Keyboard navigation: Full support
+
+### Browser Support
+- Chrome: Latest 2 versions
+- Firefox: Latest 2 versions
+- Safari: Latest 2 versions
+- Edge: Latest 2 versions
+- Mobile: iOS Safari, Chrome Android
+
+### Internationalization
+- Languages: [List]
+- RTL support: Yes/No
+- Date/time formats: Locale-aware
+- Currency formats: Locale-aware
+```
+
+---
+
+## Deliverables Checklist
+
+Every requirement analysis must produce:
+
+- [ ] **Project Brief** - Business context, goals, constraints
+- [ ] **User Personas** (2-3 minimum)
+- [ ] **User Story Map** - All stories with priorities
+- [ ] **Feature Specifications** - One per page/screen
+- [ ] **State Matrices** - All component states
+- [ ] **User Flow Diagrams** - Mermaid flowcharts
+- [ ] **Error Scenario Matrix** - All error cases
+- [ ] **Acceptance Criteria** - Gherkin format
+- [ ] **API Requirements** - Endpoints, data models
+- [ ] **Analytics Requirements** - Events, metrics
+- [ ] **Non-Functional Requirements** - Performance, security, a11y
+

package/.claude/skills/react-best-practices/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: react-best-practices
+description: |
+  React and Next.js performance optimization guidelines from Vercel Engineering.
+
+  Use when:
+  - Writing new React components or Next.js pages
+  - Implementing data fetching (client or server-side)
+  - Reviewing code for performance issues
+  - Optimizing bundle size or load times
+  - Refactoring React/Next.js codebases
+
+  Key Features:
+  - 40+ rules across 8 categories, prioritized by impact
+  - Detailed examples comparing incorrect vs correct implementations
+  - Specific impact metrics to guide optimization decisions
+
+  Categories (by priority):
+  - CRITICAL: Eliminating Waterfalls, Bundle Size Optimization
+  - HIGH: Server-Side Performance
+  - MEDIUM-HIGH: Client-Side Data Fetching
+  - MEDIUM: Re-render Optimization, Rendering Performance
+  - LOW-MEDIUM: JavaScript Performance
+  - LOW: Advanced Patterns
+allowed-tools: [read, write, execute, grep, glob]
+---
+
+# React Best Practices
+
+**Version 1.0.0** | Vercel Engineering | January 2026
+
+Comprehensive performance optimization guide for React and Next.js applications.
+
+## Quick Reference
+
+| Category | Impact | Key Rules |
+|----------|--------|-----------|
+| Eliminating Waterfalls | **CRITICAL** | Promise.all(), defer await, Suspense boundaries |
+| Bundle Size | **CRITICAL** | Avoid barrel imports, dynamic imports, preload |
+| Server-Side | **HIGH** | LRU cache, React.cache(), parallel fetching |
+| Client-Side | **MEDIUM-HIGH** | SWR deduplication, event listener dedup |
+| Re-render | **MEDIUM** | Functional setState, lazy init, transitions |
+| Rendering | **MEDIUM** | content-visibility, hoist JSX, Activity |
+| JavaScript | **LOW-MEDIUM** | Set/Map lookups, cache function results |
+| Advanced | **LOW** | useLatest, event handler refs |
+
+---
+
+## Decision Tree
+
+```
+Performance Issue?
+       │
+       ├── Slow initial load?
+       │   ├── Check bundle size → `references/bundle-optimization.md`
+       │   └── Check waterfalls → `references/eliminating-waterfalls.md`
+       │
+       ├── Slow server response?
+       │   └── Check server patterns → `references/server-performance.md`
+       │
+       ├── UI feels sluggish?
+       │   ├── Check re-renders → `references/rerender-optimization.md`
+       │   └── Check rendering → `references/rendering-performance.md`
+       │
+       └── Data fetching issues?
+           └── Check client patterns → `references/client-data-fetching.md`
+```
+
+---
+
+## 🔴 Critical Rules (Must Follow)
+
+### 1. Avoid Barrel File Imports
+
+**Impact: 200-800ms import cost**
+
+```tsx
+// ❌ Incorrect: imports entire library
+import { Check, X, Menu } from 'lucide-react'
+
+// ✅ Correct: imports only what you need
+import Check from 'lucide-react/dist/esm/icons/check'
+import X from 'lucide-react/dist/esm/icons/x'
+
+// ✅ Alternative: Next.js 13.5+ config
+// next.config.js
+module.exports = {
+  experimental: {
+    optimizePackageImports: ['lucide-react', '@mui/material']
+  }
+}
+```
+
+### 2. Promise.all() for Independent Operations
+
+**Impact: 2-10× improvement**
+
+```tsx
+// ❌ Incorrect: sequential, 3 round trips
+const user = await fetchUser()
+const posts = await fetchPosts()
+const comments = await fetchComments()
+
+// ✅ Correct: parallel, 1 round trip
+const [user, posts, comments] = await Promise.all([
+  fetchUser(),
+  fetchPosts(),
+  fetchComments()
+])
+```
+
+### 3. Dynamic Imports for Heavy Components
+
+**Impact: Directly affects TTI and LCP**
+
+```tsx
+// ❌ Incorrect: Monaco bundles with main chunk ~300KB
+import { MonacoEditor } from './monaco-editor'
+
+// ✅ Correct: Monaco loads on demand
+import dynamic from 'next/dynamic'
+
+const MonacoEditor = dynamic(
+  () => import('./monaco-editor').then(m => m.MonacoEditor),
+  { ssr: false }
+)
+```
+
+### 4. Strategic Suspense Boundaries
+
+**Impact: Faster initial paint**
+
+```tsx
+// ❌ Incorrect: wrapper blocked by data fetching
+async function Page() {
+  const data = await fetchData() // Blocks entire page
+  return (
+    <div>
+      <Sidebar />
+      <DataDisplay data={data} />
+    </div>
+  )
+}
+
+// ✅ Correct: wrapper shows immediately
+function Page() {
+  return (
+    <div>
+      <Sidebar />
+      <Suspense fallback={<Skeleton />}>
+        <DataDisplay />
+      </Suspense>
+    </div>
+  )
+}
+
+async function DataDisplay() {
+  const data = await fetchData() // Only blocks this component
+  return <div>{data.content}</div>
+}
+```
+
+---
+
+## Reference Navigation
+
+| Situation | Read This |
+|-----------|-----------|
+| Bundle too large | `references/bundle-optimization.md` |
+| Slow initial load | `references/eliminating-waterfalls.md` |
+| Server response slow | `references/server-performance.md` |
+| Client data fetching | `references/client-data-fetching.md` |
+| Too many re-renders | `references/rerender-optimization.md` |
+| Rendering performance | `references/rendering-performance.md` |
+| JavaScript hot paths | `references/javascript-performance.md` |
+| Advanced patterns | `references/advanced-patterns.md` |
+| **Complete guide** | `references/complete-guide.md` |
+
+---
+
+## Output Contract
+
+```markdown
+## Performance Review
+
+### Issues Found
+| Priority | Issue | File:Line | Fix |
+|----------|-------|-----------|-----|
+| CRITICAL | Barrel import | src/App.tsx:5 | Direct import |
+| HIGH | Sequential await | src/api.ts:20 | Promise.all() |
+
+### Recommendations
+- [List of specific improvements]
+
+### Impact Estimate
+- Bundle size: -X KB
+- Load time: -X ms
+```

package/.claude/skills/react-best-practices/references/advanced-patterns.md

@@ -0,0 +1,94 @@
+# Advanced Patterns
+
+**Impact: LOW**
+
+Advanced patterns for specific cases that require careful implementation.
+
+---
+
+## 1. Store Event Handlers in Refs
+
+**Impact: LOW (stable subscriptions)**
+
+Store callbacks in refs when used in effects that shouldn't re-subscribe on callback changes.
+
+```tsx
+// ❌ Incorrect: re-subscribes on every render
+function useWindowEvent(event: string, handler: () => void) {
+  useEffect(() => {
+    window.addEventListener(event, handler)
+    return () => window.removeEventListener(event, handler)
+  }, [event, handler])
+}
+
+// ✅ Correct: stable subscription
+import { useEffectEvent } from 'react'
+
+function useWindowEvent(event: string, handler: () => void) {
+  const onEvent = useEffectEvent(handler)
+
+  useEffect(() => {
+    window.addEventListener(event, onEvent)
+    return () => window.removeEventListener(event, onEvent)
+  }, [event])
+}
+```
+
+`useEffectEvent` provides a cleaner API: it creates a stable function reference that always calls the latest version of the handler.
+
+---
+
+## 2. useLatest for Stable Callback Refs
+
+**Impact: LOW (prevents effect re-runs)**
+
+Access latest values in callbacks without adding them to dependency arrays.
+
+**Implementation:**
+
+```typescript
+function useLatest<T>(value: T) {
+  const ref = useRef(value)
+  useEffect(() => {
+    ref.current = value
+  }, [value])
+  return ref
+}
+```
+
+**Usage:**
+
+```tsx
+// ❌ Incorrect: effect re-runs on every callback change
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+  const [query, setQuery] = useState('')
+
+  useEffect(() => {
+    const timeout = setTimeout(() => onSearch(query), 300)
+    return () => clearTimeout(timeout)
+  }, [query, onSearch])
+}
+
+// ✅ Correct: stable effect, fresh callback
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+  const [query, setQuery] = useState('')
+  const onSearchRef = useLatest(onSearch)
+
+  useEffect(() => {
+    const timeout = setTimeout(() => onSearchRef.current(query), 300)
+    return () => clearTimeout(timeout)
+  }, [query])
+}
+```
+
+---
+
+## References
+
+1. https://react.dev
+2. https://nextjs.org
+3. https://swr.vercel.app
+4. https://github.com/shuding/better-all
+5. https://github.com/isaacs/node-lru-cache
+6. https://vercel.com/blog/how-we-optimized-package-imports-in-next-js
+7. https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast