@su-record/vibe 2.7.6 → 2.7.9

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

@@ -1,304 +1,59 @@
 ---
 name: vercel-react-best-practices
-description: "React/Next.js performance optimization guide (based on Vercel engineering). Auto-activates when writing, reviewing, or refactoring React components. 45 rules across 8 priority categories."
+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
 
-Comprehensive React/Next.js performance optimization guide from the Vercel engineering team. 45 rules organized into 8 categories with an impact-based priority system.
+## Pre-check (K1)
 
-## When to Apply
+> 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.
 
-- When writing React components or Next.js pages
-- When implementing data fetching (client/server)
-- During performance-focused code reviews
-- When refactoring existing React/Next.js code
-- When optimizing bundle size or load times
+## CRITICAL Gotchas
 
-## Priority System by Category
+### Waterfall Elimination
 
-| Priority | Category | Impact | Prefix |
-|----------|----------|--------|--------|
-| 1 | Waterfall Elimination | CRITICAL | `async-` |
-| 2 | Bundle Size Optimization | CRITICAL | `bundle-` |
-| 3 | Server-side Performance | HIGH | `server-` |
-| 4 | Client Data Fetching | MEDIUM-HIGH | `client-` |
-| 5 | Re-render Optimization | MEDIUM | `rerender-` |
-| 6 | Rendering Performance | MEDIUM | `rendering-` |
-| 7 | JavaScript Performance | LOW-MEDIUM | `js-` |
-| 8 | Advanced Patterns | LOW | `advanced-` |
+| 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 |
 
-## Quick Reference — 45 Rule Index
+### Bundle Size
 
-### 1. Waterfall Elimination (CRITICAL)
+| 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 }` |
 
-| Rule | Description |
-|------|-------------|
-| `async-defer-await` | Move await to the branch where the value is actually used |
-| `async-parallel` | Use `Promise.all()` for independent operations |
-| `async-dependencies` | Use better-all for partial dependencies |
-| `async-api-routes` | Start Promises early, await late |
-| `async-suspense-boundaries` | Stream content with Suspense |
+## HIGH Gotchas
 
-**Key Example — `async-parallel` (CRITICAL):**
+### Server-side
 
-```typescript
-// ❌ Bad: sequential execution → waterfall
-const user = await getUser(id);
-const posts = await getPosts(id);
-const comments = await getComments(id);
+| 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 |
 
-// ✅ Good: parallel execution
-const [user, posts, comments] = await Promise.all([
-  getUser(id),
-  getPosts(id),
-  getComments(id),
-]);
-```
+## MEDIUM Gotchas
 
-### 2. Bundle Size Optimization (CRITICAL)
+| 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 |
 
-| Rule | Description |
-|------|-------------|
-| `bundle-barrel-imports` | Avoid barrel files, use direct imports |
-| `bundle-dynamic-imports` | Use `next/dynamic` for heavy components |
-| `bundle-defer-third-party` | Load analytics/logging after hydration |
-| `bundle-conditional` | Load modules only when feature is enabled |
-| `bundle-preload` | Preload on hover/focus for perceived speed |
+## Done Criteria (K4)
 
-**Key Example — `bundle-barrel-imports` (CRITICAL):**
-
-```typescript
-// ❌ Bad: barrel import → included in entire bundle
-import { Button } from "@/components";
-
-// ✅ Good: direct import → tree-shakeable
-import { Button } from "@/components/Button";
-```
-
-### 3. Server-side Performance (HIGH)
-
-| Rule | Description |
-|------|-------------|
-| `server-cache-react` | Deduplicate per-request with `React.cache()` |
-| `server-cache-lru` | Cross-request caching with LRU cache |
-| `server-serialization` | Minimize data passed to client components |
-| `server-parallel-fetching` | Redesign component structure for parallel fetching |
-| `server-after-nonblocking` | Non-blocking post-processing with `after()` |
-
-**Key Example — `server-cache-react` (HIGH):**
-
-```typescript
-// ❌ Bad: duplicate DB calls within same request
-async function Layout() {
-  const user = await getUser(); // call 1
-  return <Header user={user}><Content /></Header>;
-}
-async function Content() {
-  const user = await getUser(); // call 2 (duplicate)
-  return <div>{user.name}</div>;
-}
-
-// ✅ Good: per-request deduplication with React.cache
-import { cache } from "react";
-const getUser = cache(async () => {
-  return await db.user.findUnique({ where: { id: currentUserId } });
-});
-```
-
-### 4. Client Data Fetching (MEDIUM-HIGH)
-
-| Rule | Description |
-|------|-------------|
-| `client-swr-dedup` | Auto-deduplicate requests with SWR |
-| `client-event-listeners` | Prevent duplicate global event listener registration |
-
-**Key Example — `client-swr-dedup` (MEDIUM-HIGH):**
-
-```typescript
-// ❌ Bad: duplicate API calls from multiple components
-function Header() {
-  const [user, setUser] = useState(null);
-  useEffect(() => { fetch("/api/user").then(r => r.json()).then(setUser); }, []);
-  return <div>{user?.name}</div>;
-}
-function Sidebar() {
-  const [user, setUser] = useState(null);
-  useEffect(() => { fetch("/api/user").then(r => r.json()).then(setUser); }, []);
-  return <div>{user?.email}</div>;
-}
-
-// ✅ Good: auto-deduplication + caching with SWR
-import useSWR from "swr";
-function useUser() {
-  return useSWR("/api/user", fetcher);
-}
-function Header() {
-  const { data: user } = useUser(); // same key → auto-deduplicated
-  return <div>{user?.name}</div>;
-}
-function Sidebar() {
-  const { data: user } = useUser(); // only 1 network request
-  return <div>{user?.email}</div>;
-}
-```
-
-### 5. Re-render Optimization (MEDIUM)
-
-| Rule | Description |
-|------|-------------|
-| `rerender-defer-reads` | Avoid subscribing to state used only in callbacks |
-| `rerender-memo` | Isolate expensive computations in memoized components |
-| `rerender-dependencies` | Use primitive values for effect dependencies |
-| `rerender-derived-state` | Subscribe to derived booleans instead of raw data |
-| `rerender-functional-setstate` | Use functional setState for stable callbacks |
-| `rerender-lazy-state-init` | Pass functions for expensive initial values |
-| `rerender-transitions` | Use startTransition for non-urgent updates |
-
-**Key Example — `rerender-memo` (MEDIUM):**
-
-```typescript
-// ❌ Bad: expensive computation re-runs on every parent re-render
-function Dashboard({ data, filter }) {
-  const processed = expensiveProcess(data); // runs every time
-  return <Chart data={processed} />;
-}
-
-// ✅ Good: isolate expensive computation in memoized component
-const ProcessedChart = memo(function ProcessedChart({ data }: { data: Data[] }) {
-  const processed = expensiveProcess(data);
-  return <Chart data={processed} />;
-});
-```
-
-### 6. Rendering Performance (MEDIUM)
-
-| Rule | Description |
-|------|-------------|
-| `rendering-animate-svg-wrapper` | Animate div wrapper instead of SVG elements |
-| `rendering-content-visibility` | Apply content-visibility to long lists |
-| `rendering-hoist-jsx` | Hoist static JSX outside components |
-| `rendering-svg-precision` | Reduce SVG coordinate precision |
-| `rendering-hydration-no-flicker` | Prevent client-only data flicker with inline scripts |
-| `rendering-activity` | Use Activity component for show/hide |
-| `rendering-conditional-render` | Use ternary instead of `&&` |
-
-**Key Example — `rendering-content-visibility` (MEDIUM):**
-
-```css
-/* ❌ Bad: render all items in a long list immediately */
-.list-item {
-  /* default: render all items */
-}
-
-/* ✅ Good: defer rendering for off-viewport items */
-.list-item {
-  content-visibility: auto;
-  contain-intrinsic-size: 0 80px;
-}
-```
-
-**Key Example — `rendering-hoist-jsx` (MEDIUM):**
-
-```typescript
-// ❌ Bad: static JSX recreated on every re-render
-function Page({ data }) {
-  return (
-    <div>
-      <header><h1>My App</h1><nav>...</nav></header>
-      <main>{data.map(item => <Card key={item.id} {...item} />)}</main>
-    </div>
-  );
-}
-
-// ✅ Good: hoist static JSX outside component
-const HEADER = <header><h1>My App</h1><nav>...</nav></header>;
-
-function Page({ data }) {
-  return (
-    <div>
-      {HEADER}
-      <main>{data.map(item => <Card key={item.id} {...item} />)}</main>
-    </div>
-  );
-}
-```
-
-### 7. JavaScript Performance (LOW-MEDIUM)
-
-| Rule | Description |
-|------|-------------|
-| `js-batch-dom-css` | Batch CSS changes via class or cssText |
-| `js-index-maps` | Index repeated lookups with Map |
-| `js-cache-property-access` | Cache object property access in loops |
-| `js-cache-function-results` | Cache function results in module-level Map |
-| `js-cache-storage` | Cache localStorage/sessionStorage reads |
-| `js-combine-iterations` | Combine multiple filter/map into single loop |
-| `js-length-check-first` | Check array length before expensive comparisons |
-| `js-early-exit` | Early return from functions |
-| `js-hoist-regexp` | Hoist RegExp creation out of loops |
-| `js-min-max-loop` | Calculate min/max with loop instead of sort |
-| `js-set-map-lookups` | Use Set/Map for O(1) lookups |
-| `js-tosorted-immutable` | Use toSorted() for immutable sorting |
-
-### 8. Advanced Patterns (LOW)
-
-| Rule | Description |
-|------|-------------|
-| `advanced-event-handler-refs` | Store event handlers in refs |
-| `advanced-use-latest` | Use useLatest for stable callback refs |
-
-**Key Example — `advanced-event-handler-refs` (LOW):**
-
-```typescript
-// ❌ Bad: event handler changes every render → effect re-runs
-function useInterval(callback: () => void, delay: number) {
-  useEffect(() => {
-    const id = setInterval(callback, delay);
-    return () => clearInterval(id);
-  }, [callback, delay]); // callback changes every time
-}
-
-// ✅ Good: ref holds latest handler → stable effect
-function useInterval(callback: () => void, delay: number) {
-  const savedCallback = useRef(callback);
-  useEffect(() => { savedCallback.current = callback; });
-  useEffect(() => {
-    const id = setInterval(() => savedCallback.current(), delay);
-    return () => clearInterval(id);
-  }, [delay]); // only depends on delay
-}
-```
-
-## Rule Count Summary by Category
-
-| Category | Rules | Impact |
-|----------|-------|--------|
-| Waterfall Elimination | 5 | CRITICAL |
-| Bundle Size Optimization | 5 | CRITICAL |
-| Server-side Performance | 5 | HIGH |
-| Client Data Fetching | 2 | MEDIUM-HIGH |
-| Re-render Optimization | 7 | MEDIUM |
-| Rendering Performance | 7 | MEDIUM |
-| JavaScript Performance | 12 | LOW-MEDIUM |
-| Advanced Patterns | 2 | LOW |
-| **Total** | **45** | |
-
-## Usage
-
-This skill provides a Quick Reference index and key examples per category. For detailed explanations and full code examples of each rule, refer to the CCPP AGENTS.md.
-
-### Priority-Based Application Strategy
-
-1. **CRITICAL (Priority 1-2)**: Must apply in all projects
-2. **HIGH (Priority 3)**: Apply when using server components
-3. **MEDIUM (Priority 4-6)**: Review first when performance issues arise
-4. **LOW (Priority 7-8)**: Selectively apply during optimization phase
-
-### VIBE Tool Integration
-
-- `core_analyze_complexity` — Analyze component complexity
-- `core_validate_code_quality` — Validate code quality
-- `/vibe.review` — 13+ agent parallel review (includes performance-reviewer)
+- [ ] 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/video-production/SKILL.md

@@ -1,222 +1,51 @@
 ---
 name: video-production
-description: "Video processing and production patterns — FFmpeg, transcoding, streaming, subtitles."
+description: "Video processing gotchas — FFmpeg, transcoding, streaming, subtitles."
 triggers: [video, ffmpeg, transcode, encode, stream, media, subtitle, thumbnail, hls, dash]
 priority: 60
 ---
 
-# Video Production Skill
+# Video Production
 
-FFmpeg 기반 비디오 처리, 트랜스코딩, 스트리밍 구성, 자막 처리 패턴 가이드.
+## Pre-check (K1)
 
-## Core Concepts
+> Are you processing video files programmatically? If just embedding a YouTube/Vimeo player, this skill is not needed.
 
-### FFmpeg CLI Wrapper Pattern
+## Gotchas
 
-FFmpeg 호출은 반드시 래퍼를 통해 수행한다. 직접 CLI 문자열을 조합하지 않는다.
+| Gotcha | Consequence | Prevention |
+|--------|-------------|------------|
+| Direct CLI string concatenation | Command injection risk | Always use wrapper library (fluent-ffmpeg for TS, ffmpeg-python for Python) |
+| No input validation | Crash on corrupted files | Always `ffprobe` input before processing — check codec, resolution, duration |
+| No temp file cleanup | Disk fills up silently | `try/finally` or cleanup handler — never leave partial outputs |
+| No progress callback | Long encoding appears frozen | Implement progress events for any operation >10s |
+| Memory loading large files | OOM on 4K+ video | Use streaming I/O, never read entire file into memory |
+| Assuming codec availability | Fails on different FFmpeg builds | Check `ffmpeg -codecs` at runtime before encoding |
+| Fixed bitrate encoding | Inconsistent quality | Use CRF-based quality (18-28 for H.264) instead |
+| No timeout | Encoding hangs forever | Set timeout + kill process on expiry |
 
-**TypeScript (fluent-ffmpeg):**
-```typescript
-import ffmpeg from 'fluent-ffmpeg';
+## Codec Quick Reference
 
-function transcodeVideo(
-  input: string,
-  output: string,
-  options: TranscodeOptions,
-): Promise<void> {
-  return new Promise((resolve, reject) => {
-    ffmpeg(input)
-      .outputOptions(buildOutputOptions(options))
-      .output(output)
-      .on('end', resolve)
-      .on('error', reject)
-      .run();
-  });
-}
-```
+| Use Case | Codec | Note |
+|----------|-------|------|
+| Maximum compatibility | H.264 (libx264) | CRF 23 default |
+| Smaller files | H.265 (libx265) | 50% smaller, slower, licensing issues |
+| Open source | VP9 (libvpx-vp9) | Good for WebM |
+| Best compression | AV1 (libaom-av1) | Very slow encoding |
 
-**Python (ffmpeg-python):**
-```python
-import ffmpeg
+## Resolution Presets
 
-def transcode_video(
-    input_path: str,
-    output_path: str,
-    codec: str = "libx264",
-    crf: int = 23,
-) -> None:
-    (
-        ffmpeg
-        .input(input_path)
-        .output(output_path, vcodec=codec, crf=crf)
-        .overwrite_output()
-        .run(capture_stdout=True, capture_stderr=True)
-    )
-```
+| Preset | Resolution | Bitrate (H.264) |
+|--------|-----------|-----------------|
+| 360p | 640x360 | 800 kbps |
+| 720p | 1280x720 | 3 Mbps |
+| 1080p | 1920x1080 | 6 Mbps |
+| 4K | 3840x2160 | 15 Mbps |
 
-### Error Handling
+## Done Criteria (K4)
 
-비디오 처리는 실패할 수 있다. 반드시 에러를 처리한다.
-
-| 에러 유형 | 원인 | 대응 |
-|-----------|------|------|
-| Codec not found | FFmpeg 빌드에 코덱 미포함 | 런타임 시 코덱 가용성 확인 |
-| Out of memory | 큰 파일 + 고해상도 | 스트리밍 처리, chunk 분할 |
-| Corrupted input | 깨진 소스 파일 | `ffprobe`로 사전 검증 |
-| Permission denied | 파일 잠금 | 임시 디렉토리 사용, 정리 보장 |
-| Timeout | 장시간 인코딩 | progress 콜백 + 타임아웃 설정 |
-
-```typescript
-// 입력 파일 사전 검증
-async function probeVideo(filePath: string): Promise<VideoMetadata> {
-  return new Promise((resolve, reject) => {
-    ffmpeg.ffprobe(filePath, (err, data) => {
-      if (err) return reject(new Error(`Invalid video: ${err.message}`));
-      const video = data.streams.find(s => s.codec_type === 'video');
-      if (!video) return reject(new Error('No video stream found'));
-      resolve({
-        width: video.width ?? 0,
-        height: video.height ?? 0,
-        duration: Number(data.format.duration ?? 0),
-        codec: video.codec_name ?? 'unknown',
-        bitrate: Number(data.format.bit_rate ?? 0),
-      });
-    });
-  });
-}
-```
-
-## Common Operations
-
-### Thumbnail Generation
-
-```typescript
-function extractThumbnail(
-  input: string,
-  output: string,
-  timeSeconds: number = 1,
-): Promise<void> {
-  return new Promise((resolve, reject) => {
-    ffmpeg(input)
-      .screenshots({
-        timestamps: [timeSeconds],
-        filename: path.basename(output),
-        folder: path.dirname(output),
-        size: '320x240',
-      })
-      .on('end', resolve)
-      .on('error', reject);
-  });
-}
-```
-
-### Resolution Presets
-
-| Preset | Resolution | Bitrate (H.264) | Use Case |
-|--------|-----------|-----------------|----------|
-| 360p | 640x360 | 800 kbps | Mobile preview |
-| 480p | 854x480 | 1.5 Mbps | Standard mobile |
-| 720p | 1280x720 | 3 Mbps | HD streaming |
-| 1080p | 1920x1080 | 6 Mbps | Full HD |
-| 4K | 3840x2160 | 15 Mbps | Ultra HD |
-
-### Codec Selection
-
-| Codec | Format | Pros | Cons |
-|-------|--------|------|------|
-| H.264 (libx264) | MP4 | Universal compatibility | Larger file size |
-| H.265 (libx265) | MP4 | 50% smaller than H.264 | Slower encoding, licensing |
-| VP9 (libvpx-vp9) | WebM | Open source, good quality | Slow encoding |
-| AV1 (libaom-av1) | MP4/WebM | Best compression | Very slow encoding |
-
-### HLS Streaming
-
-```typescript
-function generateHLS(
-  input: string,
-  outputDir: string,
-  variants: HLSVariant[] = DEFAULT_VARIANTS,
-): Promise<void> {
-  return new Promise((resolve, reject) => {
-    const cmd = ffmpeg(input);
-    for (const v of variants) {
-      cmd
-        .output(path.join(outputDir, `${v.name}.m3u8`))
-        .outputOptions([
-          `-vf scale=${v.width}:${v.height}`,
-          `-b:v ${v.bitrate}`,
-          '-hls_time 6',
-          '-hls_list_size 0',
-          '-hls_segment_filename',
-          path.join(outputDir, `${v.name}_%03d.ts`),
-        ]);
-    }
-    cmd.on('end', resolve).on('error', reject).run();
-  });
-}
-```
-
-### Subtitle Processing
-
-```typescript
-// SRT → VTT 변환
-function srtToVtt(srtContent: string): string {
-  const vtt = srtContent
-    .replace(/\r\n/g, '\n')
-    .replace(/(\d{2}):(\d{2}):(\d{2}),(\d{3})/g, '$1:$2:$3.$4');
-  return `WEBVTT\n\n${vtt}`;
-}
-
-// 자막 burn-in (하드코딩)
-function burnSubtitles(
-  input: string,
-  subtitleFile: string,
-  output: string,
-): Promise<void> {
-  return new Promise((resolve, reject) => {
-    ffmpeg(input)
-      .outputOptions([`-vf subtitles=${subtitleFile}`])
-      .output(output)
-      .on('end', resolve)
-      .on('error', reject)
-      .run();
-  });
-}
-```
-
-### Watermark
-
-```typescript
-function addWatermark(
-  input: string,
-  watermark: string,
-  output: string,
-  position: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' = 'bottom-right',
-): Promise<void> {
-  const overlayMap: Record<string, string> = {
-    'top-left': '10:10',
-    'top-right': 'W-w-10:10',
-    'bottom-left': '10:H-h-10',
-    'bottom-right': 'W-w-10:H-h-10',
-  };
-  return new Promise((resolve, reject) => {
-    ffmpeg(input)
-      .input(watermark)
-      .complexFilter([`overlay=${overlayMap[position]}`])
-      .output(output)
-      .on('end', resolve)
-      .on('error', reject)
-      .run();
-  });
-}
-```
-
-## Best Practices
-
-1. **항상 ffprobe로 입력 검증** — 처리 전에 코덱, 해상도, 무결성 확인
-2. **임시 파일 정리 보장** — try/finally 또는 cleanup handler 사용
-3. **Progress 콜백 구현** — 장시간 작업에 진행률 피드백
-4. **스트리밍 처리 선호** — 대용량 파일은 메모리에 올리지 않음
-5. **코덱 가용성 런타임 확인** — `ffmpeg -codecs`로 빌드 지원 확인
-6. **CRF 기반 품질 제어** — 비트레이트 고정보다 CRF (18-28) 사용
-7. **하드웨어 가속 활용** — NVIDIA NVENC, Intel QSV, Apple VideoToolbox 가용 시 사용
+- [ ] All FFmpeg calls go through wrapper library (no raw CLI strings)
+- [ ] Input files validated with ffprobe before processing
+- [ ] Temp files cleaned up in all paths (success + error)
+- [ ] Progress reporting for long operations
+- [ ] Codec availability checked at runtime