@su-record/vibe 2.9.17 → 2.9.19

package/skills/user-personas/templates/persona.md

@@ -1,89 +1,89 @@
-# User Persona: {{PERSONA_NAME}}
-
-> Product: {{PRODUCT_NAME}} | Research basis: {{DATA_SOURCE}} | Created: {{DATE}}
-
----
-
-## Identity
-
-| Field | Value |
-|-------|-------|
-| Name (fictional) | {{PERSONA_NAME}} |
-| Age range | {{AGE_RANGE}} |
-| Role / Title | {{ROLE}} |
-| Company size | {{COMPANY_SIZE}} (if B2B) |
-| Location | {{LOCATION}} |
-| Tech comfort | {{LOW / MEDIUM / HIGH}} |
-
-**In their own words**: "{{REPRESENTATIVE_QUOTE_FROM_RESEARCH}}"
-
----
-
-## Primary Job-to-be-Done
-
-> {{THE CORE OUTCOME THIS PERSONA IS TRYING TO ACHIEVE}}
-
-**Context**: {{WHEN AND HOW OFTEN DOES THIS JOB ARISE?}}
-**Definition of done**: {{HOW DOES THIS PERSONA KNOW THEY SUCCEEDED?}}
-
----
-
-## Top 3 Pain Points
-
-| # | Pain | Impact | Severity |
-|---|------|--------|----------|
-| 1 | {{PAIN_1}} | {{CONSEQUENCE}} | High / Med / Low |
-| 2 | {{PAIN_2}} | {{CONSEQUENCE}} | High / Med / Low |
-| 3 | {{PAIN_3}} | {{CONSEQUENCE}} | High / Med / Low |
-
----
-
-## Top 3 Desired Gains
-
-| # | Gain | How They Measure It |
-|---|------|---------------------|
-| 1 | {{GAIN_1}} | {{METRIC_OR_FEELING}} |
-| 2 | {{GAIN_2}} | {{METRIC_OR_FEELING}} |
-| 3 | {{GAIN_3}} | {{METRIC_OR_FEELING}} |
-
----
-
-## Unexpected Insight
-
-> {{A COUNTERINTUITIVE BEHAVIORAL PATTERN OR MOTIVATION FROM RESEARCH DATA}}
-
-**Why it matters for product decisions**: {{IMPLICATION}}
-
----
-
-## Current Alternatives
-
-How does this persona solve the problem today?
-
-| Alternative | Why they use it | What frustrates them |
-|-------------|----------------|----------------------|
-| {{ALT_1}} | {{REASON}} | {{FRUSTRATION}} |
-| {{ALT_2}} | {{REASON}} | {{FRUSTRATION}} |
-
----
-
-## Product Fit Assessment
-
-**How {{PRODUCT_NAME}} addresses their needs**:
-- {{FIT_POINT_1}}
-- {{FIT_POINT_2}}
-
-**Potential friction points**:
-- {{FRICTION_1}}
-- {{FRICTION_2}}
-
-**Unmet needs (future opportunities)**:
-- {{UNMET_NEED_1}}
-
----
-
-## Data Sources
-
-- {{SOURCE_1}} (e.g., "10 user interviews, March 2026")
-- {{SOURCE_2}} (e.g., "NPS survey, n=142")
-- **Data gaps**: {{WHAT WE DON'T KNOW YET}}
+# User Persona: {{PERSONA_NAME}}
+
+> Product: {{PRODUCT_NAME}} | Research basis: {{DATA_SOURCE}} | Created: {{DATE}}
+
+---
+
+## Identity
+
+| Field | Value |
+|-------|-------|
+| Name (fictional) | {{PERSONA_NAME}} |
+| Age range | {{AGE_RANGE}} |
+| Role / Title | {{ROLE}} |
+| Company size | {{COMPANY_SIZE}} (if B2B) |
+| Location | {{LOCATION}} |
+| Tech comfort | {{LOW / MEDIUM / HIGH}} |
+
+**In their own words**: "{{REPRESENTATIVE_QUOTE_FROM_RESEARCH}}"
+
+---
+
+## Primary Job-to-be-Done
+
+> {{THE CORE OUTCOME THIS PERSONA IS TRYING TO ACHIEVE}}
+
+**Context**: {{WHEN AND HOW OFTEN DOES THIS JOB ARISE?}}
+**Definition of done**: {{HOW DOES THIS PERSONA KNOW THEY SUCCEEDED?}}
+
+---
+
+## Top 3 Pain Points
+
+| # | Pain | Impact | Severity |
+|---|------|--------|----------|
+| 1 | {{PAIN_1}} | {{CONSEQUENCE}} | High / Med / Low |
+| 2 | {{PAIN_2}} | {{CONSEQUENCE}} | High / Med / Low |
+| 3 | {{PAIN_3}} | {{CONSEQUENCE}} | High / Med / Low |
+
+---
+
+## Top 3 Desired Gains
+
+| # | Gain | How They Measure It |
+|---|------|---------------------|
+| 1 | {{GAIN_1}} | {{METRIC_OR_FEELING}} |
+| 2 | {{GAIN_2}} | {{METRIC_OR_FEELING}} |
+| 3 | {{GAIN_3}} | {{METRIC_OR_FEELING}} |
+
+---
+
+## Unexpected Insight
+
+> {{A COUNTERINTUITIVE BEHAVIORAL PATTERN OR MOTIVATION FROM RESEARCH DATA}}
+
+**Why it matters for product decisions**: {{IMPLICATION}}
+
+---
+
+## Current Alternatives
+
+How does this persona solve the problem today?
+
+| Alternative | Why they use it | What frustrates them |
+|-------------|----------------|----------------------|
+| {{ALT_1}} | {{REASON}} | {{FRUSTRATION}} |
+| {{ALT_2}} | {{REASON}} | {{FRUSTRATION}} |
+
+---
+
+## Product Fit Assessment
+
+**How {{PRODUCT_NAME}} addresses their needs**:
+- {{FIT_POINT_1}}
+- {{FIT_POINT_2}}
+
+**Potential friction points**:
+- {{FRICTION_1}}
+- {{FRICTION_2}}
+
+**Unmet needs (future opportunities)**:
+- {{UNMET_NEED_1}}
+
+---
+
+## Data Sources
+
+- {{SOURCE_1}} (e.g., "10 user interviews, March 2026")
+- {{SOURCE_2}} (e.g., "NPS survey, n=142")
+- **Data gaps**: {{WHAT WE DON'T KNOW YET}}

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

@@ -1,60 +1,60 @@
----
-name: vercel-react-best-practices
-tier: core
-description: "React/Next.js performance gotchas from Vercel engineering. Non-intuitive pitfalls that LLMs commonly miss."
-triggers: [react, next.js, performance, optimization, vercel, component, rendering]
-priority: 60
----
-
-# Vercel React Best Practices
-
-## Pre-check (K1)
-
-> Is this a React/Next.js performance issue? Standard React patterns (useState, useEffect, components) don't need this skill. Activate only for performance optimization or code review.
-
-## CRITICAL Gotchas
-
-### Waterfall Elimination
-
-| Gotcha | Why Non-obvious |
-|--------|----------------|
-| **Sequential awaits** | `const a = await f1(); const b = await f2();` creates waterfall. Use `Promise.all([f1(), f2()])` for independent ops |
-| **Await placement** | Move `await` to the branch where value is actually used, not at declaration |
-| **Missing Suspense** | Wrap slow server components in `<Suspense>` to stream — don't block entire page |
-
-### Bundle Size
-
-| Gotcha | Why Non-obvious |
-|--------|----------------|
-| **Barrel imports** | `import { Button } from "@/components"` pulls entire barrel. Use `import { Button } from "@/components/Button"` |
-| **Third-party in initial bundle** | Load analytics/logging AFTER hydration with `next/dynamic` or lazy `useEffect` |
-| **Heavy components** | Charts, editors, maps → `next/dynamic` with `{ ssr: false }` |
-
-## HIGH Gotchas
-
-### Server-side
-
-| Gotcha | Fix |
-|--------|-----|
-| Duplicate DB calls across server components | Wrap with `React.cache()` for per-request dedup |
-| Large data serialized to client | Pick only needed fields before passing to client components |
-| Blocking post-processing (logging, analytics) | Use `after()` for non-blocking tasks |
-
-## MEDIUM Gotchas
-
-| Gotcha | Fix |
-|--------|-----|
-| Expensive computation re-runs on parent re-render | Isolate in `memo()` wrapped component |
-| Static JSX recreated every render | Hoist outside component: `const HEADER = <header>...</header>` |
-| Long lists render all items | `content-visibility: auto; contain-intrinsic-size: 0 80px;` on list items |
-| `{count && <Item />}` renders `0` | Use ternary: `{count > 0 ? <Item /> : null}` |
-| Event handler changes every render → effect re-runs | Store handlers in `useRef` for stable effects |
-| Object in useEffect deps | Use primitive values (id, not entire object) as dependencies |
-
-## Done Criteria (K4)
-
-- [ ] No sequential awaits for independent operations
-- [ ] No barrel imports for tree-shakeable modules
-- [ ] Server component data is `React.cache()`-wrapped where reused
-- [ ] Heavy third-party loaded after hydration
-- [ ] Long lists use `content-visibility: auto`
+---
+name: vercel-react-best-practices
+tier: core
+description: "React/Next.js performance gotchas from Vercel engineering. Non-intuitive pitfalls that LLMs commonly miss."
+triggers: [react, next.js, performance, optimization, vercel, component, rendering]
+priority: 60
+---
+
+# Vercel React Best Practices
+
+## Pre-check (K1)
+
+> Is this a React/Next.js performance issue? Standard React patterns (useState, useEffect, components) don't need this skill. Activate only for performance optimization or code review.
+
+## CRITICAL Gotchas
+
+### Waterfall Elimination
+
+| Gotcha | Why Non-obvious |
+|--------|----------------|
+| **Sequential awaits** | `const a = await f1(); const b = await f2();` creates waterfall. Use `Promise.all([f1(), f2()])` for independent ops |
+| **Await placement** | Move `await` to the branch where value is actually used, not at declaration |
+| **Missing Suspense** | Wrap slow server components in `<Suspense>` to stream — don't block entire page |
+
+### Bundle Size
+
+| Gotcha | Why Non-obvious |
+|--------|----------------|
+| **Barrel imports** | `import { Button } from "@/components"` pulls entire barrel. Use `import { Button } from "@/components/Button"` |
+| **Third-party in initial bundle** | Load analytics/logging AFTER hydration with `next/dynamic` or lazy `useEffect` |
+| **Heavy components** | Charts, editors, maps → `next/dynamic` with `{ ssr: false }` |
+
+## HIGH Gotchas
+
+### Server-side
+
+| Gotcha | Fix |
+|--------|-----|
+| Duplicate DB calls across server components | Wrap with `React.cache()` for per-request dedup |
+| Large data serialized to client | Pick only needed fields before passing to client components |
+| Blocking post-processing (logging, analytics) | Use `after()` for non-blocking tasks |
+
+## MEDIUM Gotchas
+
+| Gotcha | Fix |
+|--------|-----|
+| Expensive computation re-runs on parent re-render | Isolate in `memo()` wrapped component |
+| Static JSX recreated every render | Hoist outside component: `const HEADER = <header>...</header>` |
+| Long lists render all items | `content-visibility: auto; contain-intrinsic-size: 0 80px;` on list items |
+| `{count && <Item />}` renders `0` | Use ternary: `{count > 0 ? <Item /> : null}` |
+| Event handler changes every render → effect re-runs | Store handlers in `useRef` for stable effects |
+| Object in useEffect deps | Use primitive values (id, not entire object) as dependencies |
+
+## Done Criteria (K4)
+
+- [ ] No sequential awaits for independent operations
+- [ ] No barrel imports for tree-shakeable modules
+- [ ] Server component data is `React.cache()`-wrapped where reused
+- [ ] Heavy third-party loaded after hydration
+- [ ] Long lists use `content-visibility: auto`

package/skills/vercel-react-best-practices/rubrics/performance.md

@@ -1,82 +1,82 @@
-# React Performance Patterns
-
-## memo — Skip Re-render
-
-Wrap components that receive stable props but re-render from parent updates.
-
-```typescript
-const ItemRow = memo(function ItemRow({ item }: { item: Item }) {
-  return <tr>{item.name}</tr>;
-});
-```
-
-**When to use**: Pure display components in long lists, or children of frequently-updating parents.
-**When NOT to use**: Components that almost always re-render anyway (memo check costs CPU too).
-
-## useMemo — Cache Expensive Computation
-
-```typescript
-// Expensive filter/sort that depends on list + query
-const filtered = useMemo(
-  () => items.filter(i => i.name.includes(query)).sort(byDate),
-  [items, query]
-);
-```
-
-**Rule**: Only memoize when the computation is genuinely expensive (> 1ms). Measuring before adding is best practice.
-
-**Gotcha**: Object/array deps break memoization — use primitive values:
-
-```typescript
-// Bad: new object reference every render breaks memo
-useMemo(() => compute(config), [config]);
-
-// Good: primitive values stay stable
-useMemo(() => compute(config), [config.id, config.mode]);
-```
-
-## useCallback — Stable Function References
-
-```typescript
-// Without useCallback: new function ref → effect re-runs every render
-const handleSubmit = useCallback(
-  (e: FormEvent) => { submitForm(formData); },
-  [formData]
-);
-```
-
-**Use when**: passing callbacks to memo-wrapped children, or as useEffect dependencies.
-**Skip when**: the component receiving it is not memoized (no benefit).
-
-## Suspense — Stream Slow Components
-
-```tsx
-// Without Suspense: entire page waits for slowComponent
-// With Suspense: page streams, slot renders when ready
-<Suspense fallback={<Skeleton />}>
-  <SlowDataComponent />   {/* server component with slow fetch */}
-</Suspense>
-```
-
-**Gotcha**: Suspense boundaries must be placed at the **component that fetches**, not a parent.
-
-## useTransition — Keep UI Responsive
-
-```typescript
-const [isPending, startTransition] = useTransition();
-
-// Mark state update as non-urgent — keeps input responsive
-startTransition(() => setSearchQuery(inputValue));
-```
-
-Use for filtering, sorting, navigation — updates that can briefly lag without hurting UX.
-
-## Quick Reference
-
-| Pattern | Use Case | Skip When |
-|---------|----------|-----------|
-| `memo` | Pure component in updating tree | Almost always re-renders anyway |
-| `useMemo` | Expensive calculation | Fast computation (< 1ms) |
-| `useCallback` | Stable dep for memo/effect | Recipient is not memoized |
-| `Suspense` | Slow async data in subtree | Synchronous rendering |
-| `useTransition` | Non-urgent state updates | Critical/immediate feedback |
+# React Performance Patterns
+
+## memo — Skip Re-render
+
+Wrap components that receive stable props but re-render from parent updates.
+
+```typescript
+const ItemRow = memo(function ItemRow({ item }: { item: Item }) {
+  return <tr>{item.name}</tr>;
+});
+```
+
+**When to use**: Pure display components in long lists, or children of frequently-updating parents.
+**When NOT to use**: Components that almost always re-render anyway (memo check costs CPU too).
+
+## useMemo — Cache Expensive Computation
+
+```typescript
+// Expensive filter/sort that depends on list + query
+const filtered = useMemo(
+  () => items.filter(i => i.name.includes(query)).sort(byDate),
+  [items, query]
+);
+```
+
+**Rule**: Only memoize when the computation is genuinely expensive (> 1ms). Measuring before adding is best practice.
+
+**Gotcha**: Object/array deps break memoization — use primitive values:
+
+```typescript
+// Bad: new object reference every render breaks memo
+useMemo(() => compute(config), [config]);
+
+// Good: primitive values stay stable
+useMemo(() => compute(config), [config.id, config.mode]);
+```
+
+## useCallback — Stable Function References
+
+```typescript
+// Without useCallback: new function ref → effect re-runs every render
+const handleSubmit = useCallback(
+  (e: FormEvent) => { submitForm(formData); },
+  [formData]
+);
+```
+
+**Use when**: passing callbacks to memo-wrapped children, or as useEffect dependencies.
+**Skip when**: the component receiving it is not memoized (no benefit).
+
+## Suspense — Stream Slow Components
+
+```tsx
+// Without Suspense: entire page waits for slowComponent
+// With Suspense: page streams, slot renders when ready
+<Suspense fallback={<Skeleton />}>
+  <SlowDataComponent />   {/* server component with slow fetch */}
+</Suspense>
+```
+
+**Gotcha**: Suspense boundaries must be placed at the **component that fetches**, not a parent.
+
+## useTransition — Keep UI Responsive
+
+```typescript
+const [isPending, startTransition] = useTransition();
+
+// Mark state update as non-urgent — keeps input responsive
+startTransition(() => setSearchQuery(inputValue));
+```
+
+Use for filtering, sorting, navigation — updates that can briefly lag without hurting UX.
+
+## Quick Reference
+
+| Pattern | Use Case | Skip When |
+|---------|----------|-----------|
+| `memo` | Pure component in updating tree | Almost always re-renders anyway |
+| `useMemo` | Expensive calculation | Fast computation (< 1ms) |
+| `useCallback` | Stable dep for memo/effect | Recipient is not memoized |
+| `Suspense` | Slow async data in subtree | Synchronous rendering |
+| `useTransition` | Non-urgent state updates | Critical/immediate feedback |

package/skills/vercel-react-best-practices/rubrics/server-components.md

@@ -1,86 +1,86 @@
-# Server vs Client Component Decision Guide
-
-## Decision Tree
-
-```
-Does this component need any of the following?
-    │
-    ├─ useState / useReducer         → Client
-    ├─ useEffect / lifecycle hooks   → Client
-    ├─ Browser APIs (window, document, localStorage) → Client
-    ├─ Event handlers (onClick, onChange, onSubmit)  → Client
-    ├─ Third-party hooks (useRouter, useForm, etc.)  → Client
-    │
-    └─ None of the above?            → Server (default)
-```
-
-## Default: Server Component
-
-Next.js App Router defaults all components to Server. Only add `"use client"` when required.
-
-**Server components can:**
-- Fetch data directly (no useEffect needed)
-- Access backend resources (DB, filesystem, env secrets)
-- Reduce client bundle size (zero JS shipped)
-- Use `async/await` at the component level
-
-```tsx
-// Server component — no directive needed
-async function UserProfile({ id }: { id: string }) {
-  const user = await db.user.findUnique({ where: { id } });
-  return <div>{user?.name}</div>;
-}
-```
-
-## Client Component
-
-Add `"use client"` at the top of the file.
-
-```tsx
-"use client";
-import { useState } from "react";
-
-export function Counter() {
-  const [count, setCount] = useState(0);
-  return <button onClick={() => setCount(c => c + 1)}>{count}</button>;
-}
-```
-
-## Composition Pattern: Push Client Down
-
-Keep client boundary as low as possible. Wrap only the interactive slice, not the whole page.
-
-```tsx
-// Bad: entire section becomes client
-"use client";
-async function ProductPage({ id }: { id: string }) { ... }
-
-// Good: server fetches, client handles interaction
-async function ProductPage({ id }: { id: string }) {
-  const product = await getProduct(id);
-  return (
-    <div>
-      <ProductDetails product={product} />   {/* server */}
-      <AddToCartButton productId={id} />     {/* client — small, isolated */}
-    </div>
-  );
-}
-```
-
-## Gotchas
-
-| Mistake | Effect | Fix |
-|---------|--------|-----|
-| Importing a Client component into a Server component that passes a non-serializable prop | Runtime error | Only pass serializable data (string, number, plain object) |
-| `"use client"` on a file that only uses server features | Unnecessary client bundle | Remove directive |
-| `async` component without Suspense wrapper | Blocks entire parent render | Wrap in `<Suspense fallback={...}>` |
-| Calling `React.cache()` in a Client component | No effect — cache is server-only | Move data fetching to Server component |
-| Secrets in Client component | Exposed to browser | Move fetch to Server component or API route |
-
-## Data Fetching Boundary
-
-| Where | Pattern |
-|-------|---------|
-| Server component | `await fetch()` / direct DB call |
-| Client component | `useEffect` + fetch, or SWR/React Query |
-| Shared across server components | Wrap with `React.cache()` for per-request dedup |
+# Server vs Client Component Decision Guide
+
+## Decision Tree
+
+```
+Does this component need any of the following?
+    │
+    ├─ useState / useReducer         → Client
+    ├─ useEffect / lifecycle hooks   → Client
+    ├─ Browser APIs (window, document, localStorage) → Client
+    ├─ Event handlers (onClick, onChange, onSubmit)  → Client
+    ├─ Third-party hooks (useRouter, useForm, etc.)  → Client
+    │
+    └─ None of the above?            → Server (default)
+```
+
+## Default: Server Component
+
+Next.js App Router defaults all components to Server. Only add `"use client"` when required.
+
+**Server components can:**
+- Fetch data directly (no useEffect needed)
+- Access backend resources (DB, filesystem, env secrets)
+- Reduce client bundle size (zero JS shipped)
+- Use `async/await` at the component level
+
+```tsx
+// Server component — no directive needed
+async function UserProfile({ id }: { id: string }) {
+  const user = await db.user.findUnique({ where: { id } });
+  return <div>{user?.name}</div>;
+}
+```
+
+## Client Component
+
+Add `"use client"` at the top of the file.
+
+```tsx
+"use client";
+import { useState } from "react";
+
+export function Counter() {
+  const [count, setCount] = useState(0);
+  return <button onClick={() => setCount(c => c + 1)}>{count}</button>;
+}
+```
+
+## Composition Pattern: Push Client Down
+
+Keep client boundary as low as possible. Wrap only the interactive slice, not the whole page.
+
+```tsx
+// Bad: entire section becomes client
+"use client";
+async function ProductPage({ id }: { id: string }) { ... }
+
+// Good: server fetches, client handles interaction
+async function ProductPage({ id }: { id: string }) {
+  const product = await getProduct(id);
+  return (
+    <div>
+      <ProductDetails product={product} />   {/* server */}
+      <AddToCartButton productId={id} />     {/* client — small, isolated */}
+    </div>
+  );
+}
+```
+
+## Gotchas
+
+| Mistake | Effect | Fix |
+|---------|--------|-----|
+| Importing a Client component into a Server component that passes a non-serializable prop | Runtime error | Only pass serializable data (string, number, plain object) |
+| `"use client"` on a file that only uses server features | Unnecessary client bundle | Remove directive |
+| `async` component without Suspense wrapper | Blocks entire parent render | Wrap in `<Suspense fallback={...}>` |
+| Calling `React.cache()` in a Client component | No effect — cache is server-only | Move data fetching to Server component |
+| Secrets in Client component | Exposed to browser | Move fetch to Server component or API route |
+
+## Data Fetching Boundary
+
+| Where | Pattern |
+|-------|---------|
+| Server component | `await fetch()` / direct DB call |
+| Client component | `useEffect` + fetch, or SWR/React Query |
+| Shared across server components | Wrap with `React.cache()` for per-request dedup |