tribunal-kit 2.4.5 → 3.0.0

package/.agent/skills/performance-profiling/SKILL.md

@@ -1,197 +1,254 @@
----
-name: performance-profiling
-description: Performance profiling principles. Measurement, analysis, and optimization techniques.
-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
----
-
-# Performance Profiling Principles
-
-> Never optimize code you haven't measured.
-> The bottleneck is almost never where you expect it to be.
-
----
-
-## The Measurement-First Rule
-
-Every performance investigation follows the same sequence:
-
-```
-Measure → Identify hotspot → Form hypothesis → Change one thing → Measure again
-```
-
-Breaking this sequence — jumping straight to "fix" — wastes time and creates new problems.
-
----
-
-## What to Measure
-
-### Backend
-
-| Metric | Tool | Target |
-|---|---|---|
-| Request throughput | ab, k6, wrk | Baseline + stress test |
-| P50/P95/P99 latency | DataDog, Grafana, k6 | P99 < SLA threshold |
-| Memory usage | `process.memoryUsage()`, heap snapshot | Stable under load (no growth) |
-| CPU usage | clinic.js flame chart | Identify blocking operations |
-| Database query time | Query logs, pg_stat_statements | No query > 100ms without index |
-
-### Frontend
-
-| Metric | Tool | Target (2025 Core Web Vitals) |
-|---|---|---|
-| LCP (Largest Contentful Paint) | Lighthouse, CrUX | < 2.5s |
-| INP (Interaction to Next Paint) | Lighthouse, Web Vitals | < 200ms |
-| CLS (Cumulative Layout Shift) | Lighthouse | < 0.1 |
-| Bundle size (JS) | `npm run build` + analyzer | < 200kB initial JS |
-
----
-
-## Common Backend Bottlenecks
-
-### N+1 Queries (most common)
-
-```ts
-// ❌ 1 + N queries
-const posts = await db.post.findMany();
-for (const post of posts) {
-  post.author = await db.user.findUnique({ where: { id: post.authorId } });
-}
-
-// ✅ 2 queries total
-const posts = await db.post.findMany({ include: { author: true } });
-```
-
-**Detection:** Enable query logging. Repeated identical queries differing only by ID = N+1.
-
-### Missing Database Indexes
-
-```sql
--- EXPLAIN ANALYZE tells you if a query is doing a sequential scan
-EXPLAIN ANALYZE SELECT * FROM orders WHERE user_id = $1;
-
--- Sequential scan on large table → add index
-CREATE INDEX idx_orders_user_id ON orders(user_id);
-```
-
-### Blocking the Event Loop (Node.js)
-
-```ts
-// ❌ Synchronous CPU work blocks all requests
-const result = JSON.parse(fs.readFileSync('huge.json', 'utf8'));
-
-// ✅ Non-blocking
-const content = await fs.promises.readFile('huge.json', 'utf8');
-const result = JSON.parse(content);  // still sync but no disk I/O blocking
-```
-
----
-
-## Common Frontend Bottlenecks
-
-### Bundle Size
-
-- Identify large packages with `npx vite-bundle-visualizer` or `@next/bundle-analyzer`
-- Replace heavy packages with lighter alternatives (e.g., `date-fns` instead of `moment`)
-- Code-split routes — don't ship all JavaScript on first load
-
-### Render Performance
-
-```ts
-// ❌ Recalculates on every render
-function ExpensiveList({ items }) {
-  const sorted = items.sort((a, b) => a.name.localeCompare(b.name));
-  return sorted.map(item => <Item key={item.id} item={item} />);
-}
-
-// ✅ Recalculates only when items change
-function ExpensiveList({ items }) {
-  const sorted = useMemo(
-    () => [...items].sort((a, b) => a.name.localeCompare(b.name)),
-    [items]
-  );
-  return sorted.map(item => <Item key={item.id} item={item} />);
-}
-```
-
----
-
-## Profiling Tools
-
-| Tool | Platform | Best For |
-|---|---|---|
-| `clinic.js` (`clinic doctor`) | Node.js | CPU flame charts, memory leaks |
-| Chrome DevTools → Performance | Browser | JS execution, paint, layout |
-| `EXPLAIN ANALYZE` | PostgreSQL | Query plan analysis |
-| Lighthouse | Web | Full Core Web Vitals audit |
-| `k6` | Backend load testing | Throughput and latency under load |
-
----
-
-## Scripts
-
-| Script | Purpose | Run With |
-|---|---|---|
-| `scripts/lighthouse_audit.py` | Lighthouse performance audit | `python scripts/lighthouse_audit.py <url>` |
-
----
-
-## Output Format
-
-When this skill produces a recommendation or design decision, structure your output as:
-
-```
-━━━ Performance Profiling Recommendation ━━━━━━━━━━━━━━━━
-Decision:    [what was chosen / proposed]
-Rationale:   [why — one concise line]
-Trade-offs:  [what is consciously accepted]
-Next action: [concrete next step for the user]
-─────────────────────────────────────────────────
-Pre-Flight:  ✅ All checks passed
-             or ❌ [blocking item that must be resolved first]
-```
-
-
-
----
-
-## 🤖 LLM-Specific Traps
-
-AI coding assistants often fall into specific bad habits when dealing with this domain. These are strictly forbidden:
-
-1. **Over-engineering:** Proposing complex abstractions or distributed systems when a simpler approach suffices.
-2. **Hallucinated Libraries/Methods:** Using non-existent methods or packages. Always `// VERIFY` or check `package.json` / `requirements.txt`.
-3. **Skipping Edge Cases:** Writing the "happy path" and ignoring error handling, timeouts, or data validation.
-4. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
-5. **Silent Degradation:** Catching and suppressing errors without logging or re-raising.
-
----
-
-## 🏛️ Tribunal Integration (Anti-Hallucination)
-
-**Slash command: `/review` or `/tribunal-full`**
-**Active reviewers: `logic-reviewer` · `security-auditor`**
-
-### ❌ Forbidden AI Tropes
-
-1. **Blind Assumptions:** Never make an assumption without documenting it clearly with `// VERIFY: [reason]`.
-2. **Silent Degradation:** Catching and suppressing errors without logging or handling.
-3. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
-
-### ✅ Pre-Flight Self-Audit
-
-Review these questions before confirming output:
-```
-✅ Did I rely ONLY on real, verified tools and methods?
-✅ Is this solution appropriately scoped to the user's constraints?
-✅ Did I handle potential failure modes and edge cases?
-✅ Have I avoided generic boilerplate that doesn't add value?
-```
-
-### 🛑 Verification-Before-Completion (VBC) Protocol
-
-**CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
-- ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
-- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
+---
+name: performance-profiling
+description: Performance profiling mastery. Core Web Vitals (LCP, CLS, INP), Lighthouse auditing, JavaScript profiling, React rendering optimization, bundle analysis, memory leak detection, database query profiling (EXPLAIN ANALYZE), load testing, and performance budgets. Use when optimizing performance, debugging slow pages, or establishing performance standards.
+allowed-tools: Read, Write, Edit, Glob, Grep
+version: 2.0.0
+last-updated: 2026-04-01
+applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
+---
+
+# Performance Profiling — Measurement-Driven Optimization
+
+> "Premature optimization is the root of all evil" — but premature measurement is the root of all performance.
+> Never optimize without profiling first. The bottleneck is never where you think it is.
+
+---
+
+## Core Web Vitals
+
+```
+LCP (Largest Contentful Paint) → Loading speed
+  ✅ Good: ≤ 2.5s  │  ⚠️ Needs work: 2.5-4s  │  ❌ Poor: > 4s
+  What: Time until the largest visible element renders
+  Fix: Optimize images, preload fonts, reduce server time
+
+INP (Interaction to Next Paint) → Responsiveness
+  ✅ Good: ≤ 200ms  │  ⚠️ Needs work: 200-500ms  │  ❌ Poor: > 500ms
+  What: Delay between user interaction and visual response
+  Fix: Break long tasks, use web workers, defer non-critical JS
+
+CLS (Cumulative Layout Shift) → Visual stability
+  ✅ Good: ≤ 0.1  │  ⚠️ Needs work: 0.1-0.25  │  ❌ Poor: > 0.25
+  What: How much the page layout shifts unexpectedly
+  Fix: Set explicit dimensions on images/ads, font-display: swap
+
+TTFB (Time to First Byte) → Server responsiveness
+  ✅ Good: ≤ 800ms
+  Fix: CDN, caching, optimize database queries, use edge
+
+// ❌ HALLUCINATION TRAP: FID is deprecated. Use INP (Interaction to Next Paint).
+// FID only measured the FIRST interaction. INP measures ALL interactions.
+```
+
+---
+
+## JavaScript Profiling
+
+### Bundle Analysis
+
+```bash
+# Analyze what's in your JavaScript bundle
+npx vite-bundle-visualizer   # Vite
+npx @next/bundle-analyzer    # Next.js
+
+# Key targets:
+# Total JS < 200KB (gzipped) for initial load
+# No single dependency > 50KB (gzipped)
+# Tree-shaking working (no dead code)
+```
+
+```typescript
+// Common bundle bloat sources:
+// ❌ import _ from "lodash";           // 72KB — imports everything
+// ✅ import debounce from "lodash/debounce";  // 1KB — specific import
+
+// ❌ import { format } from "date-fns";  // may import entire library
+// ✅ import { format } from "date-fns/format";  // specific import
+
+// ❌ import moment from "moment";        // 67KB + locales
+// ✅ Use native Intl.DateTimeFormat or date-fns (tree-shakeable)
+```
+
+### React Rendering Profiling
+
+```typescript
+// React DevTools Profiler — find unnecessary re-renders
+
+// 1. Why Did You Render (development tool)
+// npm i @welldone-software/why-did-you-render -D
+
+// 2. Manual render tracking
+const RenderCounter = ({ label }: { label: string }) => {
+  const renderCount = useRef(0);
+  renderCount.current++;
+  console.log(`[${label}] rendered ${renderCount.current} times`);
+  return null;
+};
+
+// 3. React.memo — prevent re-renders when props haven't changed
+const ExpensiveList = React.memo(function ExpensiveList({ items }: Props) {
+  return items.map((item) => <ListItem key={item.id} {...item} />);
+});
+
+// 4. useMemo / useCallback — memoize expensive computations
+const sortedItems = useMemo(
+  () => items.toSorted((a, b) => a.name.localeCompare(b.name)),
+  [items],
+);
+```
+
+### Memory Leak Detection
+
+```typescript
+// Common memory leaks in JavaScript:
+// 1. Event listeners not cleaned up
+useEffect(() => {
+  const handler = () => console.log("resize");
+  window.addEventListener("resize", handler);
+  return () => window.removeEventListener("resize", handler); // ✅ cleanup
+}, []);
+
+// 2. Timers not cleared
+useEffect(() => {
+  const interval = setInterval(pollData, 5000);
+  return () => clearInterval(interval); // ✅ cleanup
+}, []);
+
+// 3. AbortController not used for fetch
+useEffect(() => {
+  const controller = new AbortController();
+  fetch("/api/data", { signal: controller.signal })
+    .then((res) => res.json())
+    .then(setData)
+    .catch((e) => { if (e.name !== "AbortError") throw e; });
+  return () => controller.abort(); // ✅ cancel on unmount
+}, []);
+
+// Detection: Chrome DevTools → Memory → Heap Snapshot
+// Take snapshot, perform action, take another, compare growth
+```
+
+---
+
+## Image Optimization
+
+```html
+<!-- Modern image loading -->
+<img
+  src="hero.webp"
+  srcset="hero-480.webp 480w, hero-768.webp 768w, hero-1200.webp 1200w"
+  sizes="(max-width: 768px) 100vw, 50vw"
+  width="1200"
+  height="800"
+  loading="lazy"
+  decoding="async"
+  alt="Product hero"
+  fetchpriority="high"
+/>
+
+<!-- Rules:
+  - ALWAYS set width and height (prevents CLS)
+  - Use WebP/AVIF (30-50% smaller than JPEG)
+  - loading="lazy" for below-the-fold images
+  - fetchpriority="high" for LCP image
+  - Use srcset for responsive images
+  - Serve from CDN with auto-format negotiation
+-->
+```
+
+---
+
+## Database Query Profiling
+
+```sql
+-- Always EXPLAIN before optimizing
+EXPLAIN ANALYZE SELECT u.*, COUNT(p.id) AS post_count
+FROM users u
+LEFT JOIN posts p ON p.author_id = u.id
+WHERE u.is_active = true
+GROUP BY u.id
+ORDER BY post_count DESC
+LIMIT 20;
+
+-- Look for:
+-- Seq Scan → needs an index (on large tables)
+-- Nested Loop → consider index or different join strategy
+-- Sort → can an index provide sorted data?
+-- execution time > 100ms → optimize
+
+-- Common fixes:
+-- Add index: CREATE INDEX idx_posts_author ON posts (author_id);
+-- Use partial index: CREATE INDEX idx_active_users ON users (id) WHERE is_active;
+-- Avoid SELECT *: SELECT only needed columns
+-- Paginate with cursor: WHERE id > $cursor ORDER BY id LIMIT 20
+```
+
+---
+
+## Performance Budgets
+
+```javascript
+// Lighthouse CI budget
+// lighthouserc.js
+module.exports = {
+  ci: {
+    assert: {
+      assertions: {
+        "categories:performance": ["error", { minScore: 0.9 }],
+        "first-contentful-paint": ["error", { maxNumericValue: 1500 }],
+        "largest-contentful-paint": ["error", { maxNumericValue: 2500 }],
+        "cumulative-layout-shift": ["error", { maxNumericValue: 0.1 }],
+        "total-byte-weight": ["error", { maxNumericValue: 500000 }],
+      },
+    },
+  },
+};
+```
+
+```
+Performance budget targets:
+  Total JS (gzipped):     < 200KB
+  Total CSS (gzipped):    < 50KB
+  Total page weight:      < 500KB
+  LCP:                    < 2.5s
+  INP:                    < 200ms
+  CLS:                    < 0.1
+  TTFB:                   < 800ms
+  Time to Interactive:    < 3.8s
+```
+
+---
+
+## 🤖 LLM-Specific Traps
+
+1. **FID Instead of INP:** FID is deprecated. Use INP (Interaction to Next Paint) for responsiveness measurement.
+2. **Optimizing Without Profiling:** Never optimize until you've measured. The bottleneck is never obvious.
+3. **`import _ from "lodash"`:** Full lodash import is 72KB. Use specific imports: `lodash/debounce`.
+4. **Images Without Dimensions:** Missing `width`/`height` on images causes CLS (layout shift).
+5. **`loading="lazy"` on LCP Image:** The hero/LCP image must NOT be lazy-loaded. Use `fetchpriority="high"`.
+6. **`SELECT *` on Large Tables:** Always select specific columns. `SELECT *` transfers unnecessary data.
+7. **Missing Cleanup in useEffect:** Event listeners, timers, and fetches without cleanup = memory leaks.
+8. **Average Latency as Metric:** Averages hide outliers. Always track P50, P95, P99.
+9. **No Performance Budget:** Without enforced budgets, performance degrades with every deploy.
+10. **Optimizing Render Before Network:** Network is usually the bottleneck, not render. Optimize TTFB first.
+
+---
+
+## 🏛️ Tribunal Integration
+
+**Slash command: `/tribunal-performance`**
+
+### ✅ Pre-Flight Self-Audit
+
+```
+✅ Did I measure BEFORE optimizing (Lighthouse, EXPLAIN ANALYZE)?
+✅ Is LCP < 2.5s and INP < 200ms?
+✅ Are images using WebP/AVIF with explicit dimensions?
+✅ Is the JS bundle < 200KB gzipped?
+✅ Are database queries using indexes (no Seq Scan on large tables)?
+✅ Are all useEffect hooks cleaning up subscriptions/timers?
+✅ Am I tracking P95/P99 latency (not just averages)?
+✅ Is there a performance budget enforced in CI?
+✅ Is the LCP image using fetchpriority="high" (not lazy)?
+✅ Are imports tree-shakeable (specific, not barrel imports)?
+```