tribunal-kit 1.0.0 → 2.4.2

package/.agent/skills/nextjs-react-expert/SKILL.md

@@ -1,286 +1,202 @@
 ---
-name: react-best-practices
-description: React and Next.js performance optimization from Vercel Engineering. Use when building React components, optimizing performance, eliminating waterfalls, reducing bundle size, reviewing code for performance issues, or implementing server/client-side optimizations.
-allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+name: nextjs-react-expert
+description: Next.js App Router and React v19+ performance optimization from Vercel Engineering. Use when building React components, optimizing performance, implementing React Compiler patterns, eliminating waterfalls, reducing JS payload, or implementing Streaming/PPR optimizations.
+allowed-tools: Read, Write, Edit, Glob, Grep
+version: 1.0.0
+last-updated: 2026-03-12
+applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
 ---
 
-# Next.js & React Performance Expert
+# React v19+ & Next.js Pro-Max Performance Patterns
 
-> **From Vercel Engineering** - 57 optimization rules prioritized by impact
-> **Philosophy:** Eliminate waterfalls first, optimize bundles second, then micro-optimize.
+> The fastest code is code that doesn't run.
+> The second fastest is code that runs on the edge and streams the result.
 
 ---
 
-## 🎯 Selective Reading Rule (MANDATORY)
+## Contemporary Paradigm Shifts
 
-**Read ONLY sections relevant to your task!** Check the content map below and load what you need.
-
-> 🔴 **For performance reviews: Start with CRITICAL sections (1-2), then move to HIGH/MEDIUM.**
+| Legacy (React 18 / Next.js Pages) | Modern (React 19 / Next.js App Router) |
+|---|---|
+| Manual `useMemo()` / `useCallback()` | **React Compiler** handles memoization natively |
+| `getServerSideProps` / Client Fetching | **React Server Components (RSC)** default |
+| `useActionState` custom hooks | **Server Actions** native mutations |
+| Loading spinners on client | **Streaming UI** & `Suspense` boundaries |
+| Static *or* Dynamic pages | **Partial Prerendering (PPR)** (Static shell, dynamic guts) |
 
 ---
 
-## 📑 Content Map
-
-| File                                    | Impact             | Rules    | When to Read                                                    |
-| --------------------------------------- | ------------------ | -------- | --------------------------------------------------------------- |
-| `1-async-eliminating-waterfalls.md`     | 🔴 **CRITICAL**    | 5 rules  | Slow page loads, sequential API calls, data fetching waterfalls |
-| `2-bundle-bundle-size-optimization.md`  | 🔴 **CRITICAL**    | 5 rules  | Large bundle size, slow Time to Interactive, First Load issues  |
-| `3-server-server-side-performance.md`   | 🟠 **HIGH**        | 7 rules  | Slow SSR, API route optimization, server-side waterfalls        |
-| `4-client-client-side-data-fetching.md` | 🟡 **MEDIUM-HIGH** | 4 rules  | Client data management, SWR patterns, deduplication             |
-| `5-rerender-re-render-optimization.md`  | 🟡 **MEDIUM**      | 12 rules | Excessive re-renders, React performance, memoization            |
-| `6-rendering-rendering-performance.md`  | 🟡 **MEDIUM**      | 9 rules  | Rendering bottlenecks, virtualization, image optimization       |
-| `7-js-javascript-performance.md`        | ⚪ **LOW-MEDIUM**  | 12 rules | Micro-optimizations, caching, loop performance                  |
-| `8-advanced-advanced-patterns.md`       | 🔵 **VARIABLE**    | 3 rules  | Advanced React patterns, useLatest, init-once                   |
+## Core Architecture Decision Framework
 
-**Total: 57 rules across 8 categories**
-
----
-
-## 🚀 Quick Decision Tree
-
-**What's your performance issue?**
+### Server vs. Client Component
+By default, everything in Next.js App Router is a Server Component. 
 
 ```
-🐌 Slow page loads / Long Time to Interactive
-  → Read Section 1: Eliminating Waterfalls
-  → Read Section 2: Bundle Size Optimization
-
-📦 Large bundle size (> 200KB)
-  → Read Section 2: Bundle Size Optimization
-  → Check: Dynamic imports, barrel imports, tree-shaking
-
-🖥️ Slow Server-Side Rendering
-  → Read Section 3: Server-Side Performance
-  → Check: Parallel data fetching, streaming
-
-🔄 Too many re-renders / UI lag
-  → Read Section 5: Re-render Optimization
-  → Check: React.memo, useMemo, useCallback
-
-🎨 Rendering performance issues
-  → Read Section 6: Rendering Performance
-  → Check: Virtualization, layout thrashing
+Default: Server Component (Zero JS sent to client)
+Switch to Client ('use client') ONLY when:
+  - Uses browser APIs (window, localStorage, navigator)
+  - Needs DOM event handlers (onClick, onChange)
+  - Needs state/effects (useState, useEffect, useOptimistic)
+```
 
-🌐 Client-side data fetching problems
-  → Read Section 4: Client-Side Data Fetching
-  → Check: SWR deduplication, localStorage
+**The Interleaved Pattern:** Never make a layout or major shell `'use client'`. 
+Pass Server Components *into* Client components as `children`.
 
-✨ Need advanced patterns
-  → Read Section 8: Advanced Patterns
+```tsx
+// ✅ Correct: The heavy static content stays on the server
+<ClientInteractiveDrawer>
+  <ServerHeavyGraph data={dbData} />
+</ClientInteractiveDrawer>
 ```
 
 ---
 
-## 📊 Impact Priority Guide
+## Extreme Waterfall Elimination
 
-**Use this order when doing comprehensive optimization:**
+The most impactful Next.js optimization is eliminating network waterfalls.
 
+```tsx
+// ❌ CRITICAL WATERFALL: 3 sequential async calls, each waits for the previous
+async function Dashboard() {
+  const user = await getUser();           // 200ms
+  const posts = await getPosts();         // 200ms (waits unnecessarily)
+  const analytics = await getAnalytics(); // 200ms (waits unnecessarily)
+  // Total: 600ms (Blocked UI)
+}
 ```
-1️⃣ CRITICAL (Biggest Gains - Do First):
-   ├─ Section 1: Eliminating Waterfalls
-   │  └─ Each waterfall adds full network latency (100-500ms+)
-   └─ Section 2: Bundle Size Optimization
-      └─ Affects Time to Interactive and Largest Contentful Paint
-
-2️⃣ HIGH (Significant Impact - Do Second):
-   └─ Section 3: Server-Side Performance
-      └─ Eliminates server-side waterfalls, faster response times
-
-3️⃣ MEDIUM (Moderate Gains - Do Third):
-   ├─ Section 4: Client-Side Data Fetching
-   ├─ Section 5: Re-render Optimization
-   └─ Section 6: Rendering Performance
-
-4️⃣ LOW (Polish - Do Last):
-   ├─ Section 7: JavaScript Performance
-   └─ Section 8: Advanced Patterns
-```
-
----
 
-## 🔗 Related Skills
+### Fix 1: Parallel Fetching
+```tsx
+// ✅ Parallel — all 3 start at the same time
+async function Dashboard() {
+  const [user, posts, analytics] = await Promise.all([
+    getUser(),
+    getPosts(),
+    getAnalytics(),
+  ]);
+  // Total: ~200ms (Blocked UI, but faster)
+}
+```
 
-| Need                    | Skill                             |
-| ----------------------- | --------------------------------- |
-| API design patterns     | `@[skills/api-patterns]`          |
-| Database optimization   | `@[skills/database-design]`       |
-| Testing strategies      | `@[skills/testing-patterns]`      |
-| UI/UX design principles | `@[skills/frontend-design]`       |
-| TypeScript patterns     | `@[skills/typescript-expert]`     |
-| Deployment & DevOps     | `@[skills/deployment-procedures]` |
+### Fix 2: Streaming UI (The Pro-Max Way)
+Do not await slow data at the page level. Wrap slow components in `<Suspense>`.
+
+```tsx
+// 🚀 PRO-MAX: Streaming Components
+export default function Dashboard() {
+  return (
+    <main>
+      <FastHeader />
+      <Suspense fallback={<AnalyticsSkeleton />}>
+        {/* React streams this HTML down when the DB resolves */}
+        <SlowAnalyticsComponent />
+      </Suspense>
+    </main>
+  );
+}
+```
 
 ---
 
-## ✅ Performance Review Checklist
-
-Before shipping to production:
-
-**Critical (Must Fix):**
-
-- [ ] No sequential data fetching (waterfalls eliminated)
-- [ ] Bundle size < 200KB for main bundle
-- [ ] No barrel imports in app code
-- [ ] Dynamic imports used for large components
-- [ ] Parallel data fetching where possible
-
-**High Priority:**
-
-- [ ] Server components used where appropriate
-- [ ] API routes optimized (no N+1 queries)
-- [ ] Suspense boundaries for data fetching
-- [ ] Static generation used where possible
+## Partial Prerendering (PPR)
 
-**Medium Priority:**
+PPR allows a single route to have both an ultra-fast static edge-cached shell, and dynamic personalized content streamed in instantly after execution.
 
-- [ ] Expensive computations memoized
-- [ ] List rendering virtualized (if > 100 items)
-- [ ] Images optimized with next/image
-- [ ] No unnecessary re-renders
-
-**Low Priority (Polish):**
-
-- [ ] Hot path loops optimized
-- [ ] RegExp patterns hoisted
-- [ ] Property access cached in loops
+- Avoid using global `cookies()` or `headers()` high up in the component tree, as this forces the entire route to be dynamic.
+- Isolate dynamic data fetching within a `<Suspense>` boundary so the rest of the page can be statically pre-rendered at build time.
 
 ---
 
-## ❌ Anti-Patterns (Common Mistakes)
-
-**DON'T:**
-
-- ❌ Use sequential `await` for independent operations
-- ❌ Import entire libraries when you need one function
-- ❌ Use barrel exports (`index.ts` re-exports) in app code
-- ❌ Skip dynamic imports for large components/libraries
-- ❌ Fetch data in useEffect without deduplication
-- ❌ Forget to memoize expensive computations
-- ❌ Use client components when server components work
+## AI & Streaming UI Responses
 
-**DO:**
-
-- ✅ Fetch data in parallel with `Promise.all()`
-- ✅ Use dynamic imports: `const Comp = dynamic(() => import('./Heavy'))`
-- ✅ Import directly: `import { specific } from 'library/specific'`
-- ✅ Use Suspense boundaries for better UX
-- ✅ Leverage React Server Components
-- ✅ Measure performance before optimizing
-- ✅ Use Next.js built-in optimizations (next/image, next/font)
-
----
+When building GenAI interfaces, waiting for complete API responses breaks the "Doherty Threshold" (400ms).
 
-## 🎯 How to Use This Skill
+- **Use the `ai` SDK (`@ai-sdk/react`)** to stream text using `useChat` or `useCompletion`.
+- **Generative UI (RSC streaming):** Stream actual React Server Components back from the LLM, not just strings.
 
-### For New Features:
-
-1. Check **Section 1 & 2** while building (prevent waterfalls, keep bundle small)
-2. Use server components by default (Section 3)
-3. Apply memoization for expensive operations (Section 5)
-
-### For Performance Reviews:
-
-1. Start with **Section 1** (waterfalls = biggest impact)
-2. Then **Section 2** (bundle size)
-3. Then **Section 3** (server-side)
-4. Finally other sections as needed
-
-### For Debugging Slow Performance:
-
-1. Identify the symptom (slow load, lag, etc.)
-2. Use Quick Decision Tree above
-3. Read relevant section
-4. Apply fixes in priority order
+```tsx
+// ✅ AI Generative UI response
+return (
+  <div>
+    Here is the weather:
+    <Suspense fallback={<WeatherSkeleton />}>
+      <WeatherCard promise={llmTools.getWeather(location)} />
+    </Suspense>
+  </div>
+)
+```
 
 ---
 
-## 📚 Learning Path
-
-**Beginner (Focus on Critical):**
-→ Section 1: Eliminating Waterfalls
-→ Section 2: Bundle Size Optimization
+## Bundle Size & JS Dropping
 
-**Intermediate (Add High Priority):**
-→ Section 3: Server-Side Performance
-→ Section 5: Re-render Optimization
-
-**Advanced (Full Optimization):**
-→ All sections + Section 8: Advanced Patterns
+- **Import strictly:** Use barrel files cautiously. Ensure `package.json` `sideEffects: false` is respected so bundlers can tree-shake.
+- **Client boundaries low:** Push `'use client'` as far down the component tree as mathematically possible.
+- **Lazy loading heavy client deps:**
+```tsx
+import dynamic from 'next/dynamic'
+// Only load D3.js when the user actually opens the modal
+const HeavyChart = dynamic(() => import('./HeavyChart'), { ssr: false })
+```
 
 ---
 
-## 🔍 Validation Script
+## Key Anti-Patterns
 
-| Script                                 | Purpose                     | Command                                                      |
-| -------------------------------------- | --------------------------- | ------------------------------------------------------------ |
-| `scripts/react_performance_checker.py` | Automated performance audit | `python scripts/react_performance_checker.py <project_path>` |
+| Pattern | Problem | Fix |
+|---|---|---|
+| Fetching via `useEffect` | Client waterfall, huge CLS, breaks SSR | Fetch in RSC or use `SWR`/`React Query` |
+| Manual `useMemo` everywhere | Hurts code readability; React 18 legacy | Trust **React Compiler** to optimize renders automatically |
+| Missing `key` on mapped lists | Complete DOM destruction on update | Use stable unique IDs (never `index`) |
+| Unhandled Server Actions | Silent errors on DB failures | Wrap in `try/catch` and return `{ error }` objects |
+| Client-side secret passing | Exposes API keys | `server-only` package + Server Actions |
 
 ---
 
-## 📖 Section Details
-
-### Section 1: Eliminating Waterfalls (CRITICAL)
-
-**Impact:** Each waterfall adds 100-500ms+ latency
-**Key Concepts:** Parallel fetching, Promise.all(), Suspense boundaries, preloading
-
-### Section 2: Bundle Size Optimization (CRITICAL)
-
-**Impact:** Directly affects Time to Interactive, Largest Contentful Paint
-**Key Concepts:** Dynamic imports, tree-shaking, barrel import avoidance
-
-### Section 3: Server-Side Performance (HIGH)
+## Output Format
 
-**Impact:** Faster server responses, better SEO
-**Key Concepts:** Parallel server fetching, streaming, API route optimization
+When this skill produces or reviews code, structure your output as follows:
 
-### Section 4: Client-Side Data Fetching (MEDIUM-HIGH)
-
-**Impact:** Reduces redundant requests, better UX
-**Key Concepts:** SWR deduplication, localStorage caching, event listeners
-
-### Section 5: Re-render Optimization (MEDIUM)
-
-**Impact:** Smoother UI, less wasted computation
-**Key Concepts:** React.memo, useMemo, useCallback, component structure
-
-### Section 6: Rendering Performance (MEDIUM)
-
-**Impact:** Better rendering efficiency
-**Key Concepts:** Virtualization, image optimization, layout thrashing
-
-### Section 7: JavaScript Performance (LOW-MEDIUM)
-
-**Impact:** Incremental improvements in hot paths
-**Key Concepts:** Loop optimization, caching, RegExp hoisting
+```
+━━━ Nextjs React Expert Report ━━━━━━━━━━━━━━━━━━━━━━━━
+Skill:       Nextjs React Expert
+Language:    [detected language / framework]
+Scope:       [N files · N functions]
+─────────────────────────────────────────────────
+✅ Passed:   [checks that passed, or "All clean"]
+⚠️  Warnings: [non-blocking issues, or "None"]
+❌ Blocked:  [blocking issues requiring fix, or "None"]
+─────────────────────────────────────────────────
+VBC status:  PENDING → VERIFIED
+Evidence:    [test output / lint pass / compile success]
+```
 
-### Section 8: Advanced Patterns (VARIABLE)
+**VBC (Verification-Before-Completion) is mandatory.**
+Do not mark status as VERIFIED until concrete terminal evidence is provided.
 
-**Impact:** Specific use cases
-**Key Concepts:** useLatest hook, init-once patterns, event handler refs
 
 ---
 
-## 🎓 Best Practices Summary
-
-**Golden Rules:**
+## 🏛️ Tribunal Integration (Anti-Hallucination)
 
-1. **Measure first** - Use React DevTools Profiler, Chrome DevTools
-2. **Biggest impact first** - Waterfalls → Bundle → Server → Micro
-3. **Don't over-optimize** - Focus on real bottlenecks
-4. **Use platform features** - Next.js has optimizations built-in
-5. **Think about users** - Real-world conditions matter
+**Slash command: `/tribunal-frontend`**
+**Active reviewers: `logic` · `security` · `frontend` · `type-safety`**
 
-**Performance Mindset:**
+### ❌ Forbidden AI Tropes in Next.js/React
 
-- Every `await` in sequence = potential waterfall
-- Every `import` = potential bundle bloat
-- Every re-render = wasted computation (if unnecessary)
-- Server components = less JavaScript to ship
-- Measure, don't guess
+1. **`"use client"` on everything** — do not convert Server Components to Client unless interaction/state is strictly required.
+2. **`getServerSideProps` in App Router** — never hallucinate legacy Pages router data fetching in an App Router context.
+3. **Unnecessary `useEffect` fetching** — always prefer Server Components or SWR/React Query for data fetching.
+4. **Vercel clones** — do not default to generic black/white Vercel aesthetics unless instructed.
+5. **Missing `key` in maps** — always provide a unique, stable key. No using iteration index as the key.
 
----
+### ✅ Pre-Flight Self-Audit
 
-**Source:** Vercel Engineering
-**Date:** January 2026
-**Version:** 1.0.0
-**Total Rules:** 57 across 8 categories
+Review these questions before generating React/Next.js code:
+```
+✅ Did I maximize Server Component usage and isolate `'use client'` boundaries?
+✅ Are there any sequential network calls creating a waterfall? If so, did I use `Promise.all` or `Suspense`?
+✅ Did I ensure no sensitive environment variables leak to the client?
+✅ Did I use `next/image` and `next/link` instead of raw `<img>` and `<a>` when appropriate?
+✅ Did I implement proper loading/error boundaries (`loading.tsx`, `error.tsx`)?
+```