@chinhae/atw-cli 0.6.0 → 0.7.0

package/dist/templates/common/bundled-skills/atw-performance/references/performance-checklist.md

@@ -0,0 +1,238 @@
+# Performance Checklist
+
+Quick reference checklist for web application performance. Use alongside the `atw-performance` skill.
+
+## Table of Contents
+
+- [Core Web Vitals Targets](#core-web-vitals-targets)
+- [TTFB Diagnosis](#ttfb-diagnosis)
+- [Frontend Checklist](#frontend-checklist)
+- [Backend Checklist](#backend-checklist)
+- [Caching Strategies](#caching-strategies)
+- [Measurement Commands](#measurement-commands)
+- [Common Anti-Patterns](#common-anti-patterns)
+
+## Core Web Vitals Targets
+
+| Metric | Good | Needs Work | Poor |
+|--------|------|------------|------|
+| LCP (Largest Contentful Paint) | ≤ 2.5s | ≤ 4.0s | > 4.0s |
+| INP (Interaction to Next Paint) | ≤ 200ms | ≤ 500ms | > 500ms |
+| CLS (Cumulative Layout Shift) | ≤ 0.1 | ≤ 0.25 | > 0.25 |
+
+## TTFB Diagnosis
+
+When TTFB is slow (> 800ms), check each component in DevTools Network waterfall:
+
+- [ ] **DNS resolution** slow → add `<link rel="dns-prefetch">` or `<link rel="preconnect">` for known origins
+- [ ] **TCP/TLS handshake** slow → enable HTTP/2, consider edge deployment, verify keep-alive
+- [ ] **Server processing** slow → profile backend, check slow queries, add caching
+
+## Frontend Checklist
+
+### Images
+- [ ] Images use modern formats (WebP, AVIF)
+- [ ] Images are responsively sized (`srcset` and `sizes`)
+- [ ] Images and `<source>` elements have explicit `width` and `height` (prevents CLS in art direction)
+- [ ] Below-the-fold images use `loading="lazy"` and `decoding="async"`
+- [ ] Hero/LCP images use `fetchpriority="high"` and no lazy loading
+
+### JavaScript
+- [ ] Bundle size under 200KB gzipped (initial load)
+- [ ] Code splitting with dynamic `import()` for routes and heavy features
+- [ ] Tree shaking enabled (verify dependency ships ESM and marks `sideEffects: false`)
+- [ ] No blocking JavaScript in `<head>` (use `defer` or `async`)
+- [ ] Heavy computation offloaded to Web Workers (if applicable)
+- [ ] `React.memo()` on expensive components that re-render with same props
+- [ ] `useMemo()` / `useCallback()` only where profiling shows benefit
+- [ ] Long tasks (> 50ms) broken up to keep the main thread available — main lever for INP
+- [ ] `yieldToMain` pattern used inside long-running loops so input events can run between chunks
+- [ ] Modern scheduling APIs used where available: `scheduler.yield()` (preferred), `scheduler.postTask()` with priorities, `isInputPending()` to yield only when needed
+- [ ] `requestIdleCallback` for deferrable, non-urgent work (analytics flush, prefetch, warmup)
+- [ ] Non-critical work deferred out of event handlers (e.g. analytics, logging) so the response to the interaction is not delayed
+- [ ] Third-party scripts loaded with `async` / `defer`, audited for size, and fronted by a facade when heavy (chat widgets, embeds)
+
+### CSS
+- [ ] Critical CSS inlined or preloaded
+- [ ] No render-blocking CSS for non-critical styles
+- [ ] No CSS-in-JS runtime cost in production (use extraction)
+
+### Fonts
+- [ ] Limited to 2–3 font families, 2–3 weights each (every additional weight is another request)
+- [ ] WOFF2 format only (smallest, universal support — skip WOFF/TTF/EOT)
+- [ ] Self-hosted when possible (third-party font CDNs add DNS + TCP + TLS round-trips)
+- [ ] LCP-critical fonts preloaded: `<link rel="preload" as="font" type="font/woff2" crossorigin>`
+- [ ] `font-display: swap` (or `optional` for non-critical) to avoid FOIT blocking render
+- [ ] Subsetted via `unicode-range` to ship only the glyphs each page needs
+- [ ] Variable fonts considered when multiple weights/styles are required (one file replaces many)
+- [ ] Fallback font metrics adjusted with `size-adjust`, `ascent-override`, `descent-override` to reduce CLS on font swap
+- [ ] System font stack considered before any custom font
+
+### Network
+- [ ] Static assets cached with long `max-age` + content hashing
+- [ ] API responses cached where appropriate (`Cache-Control`)
+- [ ] HTTP/2 or HTTP/3 enabled
+- [ ] Resources preconnected (`<link rel="preconnect">`) for known origins
+- [ ] `fetchpriority` used on critical non-image resources (e.g., key `<link rel="preload">`, above-the-fold `<script>`) — not only on `<img>`
+- [ ] No unnecessary redirects
+
+### Rendering
+- [ ] No layout thrashing (forced synchronous layouts)
+- [ ] Animations use `transform` and `opacity` (GPU-accelerated)
+- [ ] Long lists use virtualization (e.g., `react-window`)
+- [ ] No unnecessary full-page re-renders
+- [ ] Off-screen sections use `content-visibility: auto` with `contain-intrinsic-size` to skip layout/paint of non-visible areas
+- [ ] No `unload` event handlers and no `Cache-Control: no-store` on HTML responses — preserves back/forward cache (bfcache) eligibility
+
+## Backend Checklist
+
+### Database
+- [ ] No N+1 query patterns (use eager loading / joins)
+- [ ] Queries have appropriate indexes
+- [ ] List endpoints paginated (never `SELECT * FROM table`)
+- [ ] Connection pooling configured
+- [ ] Slow query logging enabled
+
+#### Query plans
+- [ ] `EXPLAIN ANALYZE` captured **before** the fix, not just after — it is the baseline
+- [ ] `Seq Scan` on a large table understood: index missing, unusable, or genuinely not worth it
+- [ ] Estimated vs actual `rows=` within an order of magnitude (if not, refresh statistics before touching indexes)
+- [ ] No `Sort` node that a composite index could absorb
+- [ ] Plan re-checked after the change — an index that did not change the plan gets reverted
+
+#### Index strategy
+- [ ] Composite index column order is equality first, then range/sort
+- [ ] Index covers the query shape (filter + sort), not just one column in isolation
+- [ ] Covering index considered for hot read paths (index-only scan avoids the heap fetch)
+- [ ] Not indexing low-selectivity columns *for the dominant value*; a partial index still serves the rare-value query (`WHERE status = 'failed'`)
+- [ ] Expression index used where the query applies a function (`lower(email)`)
+- [ ] Full-text or trigram index used for leading-wildcard search, not a B-tree
+- [ ] Write cost measured on write-heavy tables (every index taxes every `INSERT`/`UPDATE`)
+- [ ] Unused and duplicate indexes dropped (they cost writes and buy nothing)
+
+#### Connection pooling
+- [ ] One pool per process, not per request or per module
+- [ ] `instances × pool max` stays under the database's `max_connections`
+- [ ] `connectionTimeoutMillis` set so exhaustion fails fast instead of queueing forever
+- [ ] Exhaustion diagnosed before resizing: find what holds connections (long transactions, missing `await`, leaked clients)
+- [ ] Serverless / autoscaling fronted by a multiplexing proxy (pgbouncer, RDS Proxy) rather than a larger pool
+
+### API
+- [ ] Response times < 200ms (p95)
+- [ ] No synchronous heavy computation in request handlers
+- [ ] Bulk operations instead of loops of individual calls
+- [ ] Response compression (gzip/brotli)
+- [ ] Appropriate caching (in-memory, Redis, CDN)
+
+### Infrastructure
+- [ ] CDN for static assets
+- [ ] Server located close to users (or edge deployment)
+- [ ] Horizontal scaling configured (if needed)
+- [ ] Health check endpoint for load balancer
+
+## Caching Strategies
+
+The decision material (which layer, which invalidation strategy, what never to cache) lives in the `atw-performance` skill's `./performance-optimization.md`. This section covers the read/write patterns and the checklist.
+
+### Read and write patterns
+
+| Pattern | How it works | Use when | Watch out for |
+|---|---|---|---|
+| **Cache-aside** (lazy) | App checks cache, on miss reads origin and populates | Default choice; read-heavy, tolerant of a cold first hit | Every miss hits the origin, so it needs stampede protection |
+| **Read-through** | Cache layer itself loads on miss | You want the load path in one place, not at every call site | Hides origin latency; a slow origin looks like a slow cache |
+| **Write-through** | Write goes to cache and origin together, synchronously | Reads must never see a stale value after a write | Adds cache latency to every write |
+| **Write-behind** (write-back) | Write hits cache, origin updated asynchronously | Write-heavy, and the origin is the bottleneck | Data loss window if the cache dies before the flush. Needs durability you can defend |
+
+### Negative caching
+
+Cache the *absence* of a result too. A key that misses on every lookup (a nonexistent user ID probed in a loop, a 404 asset) sends every request to the origin, which is a cache that only protects the happy path.
+
+- Store an explicit "not found" sentinel with a **shorter** TTL than positive entries
+- Keep the negative TTL short enough that a newly created record appears promptly
+- Never let an origin *error* become a negative cache entry, or one failing minute becomes many
+
+### Request coalescing (stampede protection)
+
+One recompute, N waiters. Prevents a hot key's expiry from delivering the full concurrent load to the origin:
+
+```typescript
+const inFlight = new Map<string, Promise<unknown>>();
+
+function loadOnce<T>(key: string, fetcher: () => Promise<T>): Promise<T> {
+  const existing = inFlight.get(key) as Promise<T> | undefined;
+  if (existing) return existing;
+  const p = fetcher().finally(() => inFlight.delete(key));
+  inFlight.set(key, p);
+  return p;
+}
+```
+
+For a shared cache, the same idea needs a distributed lock, or `stale-while-revalidate` so waiters serve the stale value instead of blocking.
+
+### Cache checklist
+- [ ] The cached call was measured as expensive first (caching a fast call adds a hop and buys nothing)
+- [ ] Read/write ratio justifies the cache (re-read far more often than written)
+- [ ] Cache key includes every input the response varies on: tenant, viewer, locale, permissions, feature flags
+- [ ] No per-user data cached under a key that does not identify the user
+- [ ] One invalidation strategy chosen (TTL, event/tag, or versioned keys), not an accidental mix
+- [ ] Acceptable staleness window written down, not implied by whatever TTL was typed
+- [ ] Stampede protection on hot keys (coalescing, lock, or `stale-while-revalidate`)
+- [ ] Negative results cached with a shorter TTL; origin errors never cached
+- [ ] Eviction policy and memory ceiling set (an unbounded cache is a memory leak)
+- [ ] Hit rate monitored — a cache nobody measures is an assumption, and a low hit rate is pure overhead
+- [ ] Nothing cached whose staleness is a correctness bug (balances, permissions, inventory at checkout)
+
+## Measurement Commands
+
+### INP field data and DevTools workflow
+
+1. **Field data first** — check [CrUX Vis](https://developer.chrome.com/docs/crux/vis) or your RUM tool for real-user INP before optimising
+2. **Identify slow interactions** — open DevTools → Performance panel → record while interacting; look for long tasks triggered by clicks/keystrokes
+3. **Test on mid-range Android** — INP issues often only surface on slower hardware; use a real device or DevTools CPU throttling (4×–6× slowdown)
+
+```bash
+# Lighthouse CLI
+npx lighthouse https://localhost:3000 --output json --output-path ./report.json
+
+# Bundle analysis
+npx webpack-bundle-analyzer stats.json
+# or for Vite:
+npx vite-bundle-visualizer
+
+# Check bundle size
+npx bundlesize
+```
+
+```javascript
+// Web Vitals in code
+import { onLCP, onINP, onCLS } from 'web-vitals';
+onLCP(console.log);
+onINP(console.log);
+onCLS(console.log);
+
+// INP with interaction-level detail (attribution build)
+import { onINP } from 'web-vitals/attribution';
+onINP(({ value, attribution }) => {
+  const { interactionTarget, inputDelay, processingDuration, presentationDelay } = attribution;
+  console.log({ value, interactionTarget, inputDelay, processingDuration, presentationDelay });
+});
+```
+
+## Common Anti-Patterns
+
+| Anti-Pattern | Impact | Fix |
+|---|---|---|
+| N+1 queries | Linear DB load growth | Use joins, includes, or batch loading |
+| Unbounded queries | Memory exhaustion, timeouts | Always paginate, add LIMIT |
+| Missing indexes | Slow reads as data grows | Add indexes for filtered/sorted columns |
+| Indexing without reading the plan | Write cost paid, read gain unproven | `EXPLAIN ANALYZE` before and after; revert if the plan is unchanged |
+| Redundant / unused indexes | Every write pays for them | Audit usage stats, drop what nothing reads |
+| Connection pool per request | Exhausts `max_connections` under load | One pool per process; proxy for serverless |
+| Cache key missing the viewer | One user's data served to another | Key on tenant, viewer, locale, permissions |
+| Unbounded cache | Memory leak wearing an optimization's clothing | Set eviction policy and a memory ceiling |
+| Cache stampede on a hot key | Origin takes full concurrent load at expiry | Coalesce misses, or `stale-while-revalidate` |
+| Layout thrashing | Jank, dropped frames | Batch DOM reads, then batch writes |
+| Unoptimized images | Slow LCP, wasted bandwidth | Use WebP, responsive sizes, lazy load |
+| Large bundles | Slow Time to Interactive | Code split, tree shake, audit deps |
+| Blocking main thread | Poor INP, unresponsive UI | Chunk long tasks with `scheduler.yield()` / `yieldToMain`, offload to Web Workers |
+| Memory leaks | Growing memory, eventual crash | Clean up listeners, intervals, refs |

package/dist/templates/common/bundled-skills/atw-performance/references/performance-optimization.md

@@ -0,0 +1,264 @@
+# Performance Optimization
+
+Attached file of the `atw-performance` skill: the measure-first workflow, the where-to-start tree, the bottleneck tables, the anti-pattern catalogue, the keep-or-revert table and the budgets. Open the part you need; the skill's own rules (the seven questions, keep or revert, the decision log) come first.
+
+## Overview
+
+Measure before optimizing. Performance work without measurement is guessing — and guessing leads to premature optimization that adds complexity without improving what matters. Profile first, identify the actual bottleneck, fix it, measure again. Optimize only what measurements prove matters.
+
+## When to Use
+
+- Performance requirements exist in the spec (load time budgets, response time SLAs)
+- Users or monitoring report slow behavior
+- Core Web Vitals scores are below thresholds
+- You suspect a change introduced a regression (it was fine and got slower after a change: that goes to the `atw-diagnosing-bugs` skill)
+- Building features that handle large datasets or high traffic
+
+**When NOT to use:** Don't optimize before you have evidence of a problem. Premature optimization adds complexity that costs more than the performance it gains.
+
+## Core Web Vitals Targets
+
+| Metric | Good | Needs Improvement | Poor |
+|--------|------|-------------------|------|
+| **LCP** (Largest Contentful Paint) | ≤ 2.5s | ≤ 4.0s | > 4.0s |
+| **INP** (Interaction to Next Paint) | ≤ 200ms | ≤ 500ms | > 500ms |
+| **CLS** (Cumulative Layout Shift) | ≤ 0.1 | ≤ 0.25 | > 0.25 |
+
+## The Optimization Workflow
+
+```
+1. MEASURE  → Establish baseline with real data
+2. IDENTIFY → Find the actual bottleneck (not assumed)
+3. FIX      → Address the specific bottleneck
+4. VERIFY   → Measure again; keep or revert
+5. GUARD    → Add monitoring or tests to prevent regression
+```
+
+### Step 1: Measure
+
+Two complementary approaches — use both:
+
+- **Synthetic (Lighthouse, DevTools Performance tab):** Controlled conditions, reproducible. Best for CI regression detection and isolating specific issues.
+- **RUM (web-vitals library, CrUX):** Real user data in real conditions. Required to validate that a fix actually improved user experience.
+
+**Frontend:**
+```javascript
+// Synthetic: Lighthouse in Chrome DevTools (or CI)
+// Chrome DevTools → Performance tab → Record
+// Chrome DevTools MCP → Performance trace
+
+// RUM: Web Vitals library in code
+import { onLCP, onINP, onCLS } from 'web-vitals';
+
+onLCP(console.log);
+onINP(console.log);
+onCLS(console.log);
+```
+
+**Backend:**
+```javascript
+// Response time logging
+// Application Performance Monitoring (APM)
+// Database query logging with timing
+
+// Simple timing
+console.time('db-query');
+const result = await db.query(...);
+console.timeEnd('db-query');
+```
+
+### Where to Start Measuring
+
+Use the symptom to decide what to measure first:
+
+```
+What is slow?
+├── First page load
+│   ├── Large bundle? --> Measure bundle size, check code splitting
+│   ├── Slow server response? --> Measure TTFB in DevTools Network waterfall
+│   │   ├── DNS long? --> Add dns-prefetch / preconnect for known origins
+│   │   ├── TCP/TLS long? --> Enable HTTP/2, check edge deployment, keep-alive
+│   │   └── Waiting (server) long? --> Profile backend, check queries and caching
+│   └── Render-blocking resources? --> Check network waterfall for CSS/JS blocking
+├── Interaction feels sluggish
+│   ├── UI freezes on click? --> Profile main thread, look for long tasks (>50ms)
+│   ├── Form input lag? --> Check re-renders, controlled component overhead
+│   └── Animation jank? --> Check layout thrashing, forced reflows
+├── Page after navigation
+│   ├── Data loading? --> Measure API response times, check for waterfalls
+│   └── Client rendering? --> Profile component render time, check for N+1 fetches
+└── Backend / API
+    ├── Single endpoint slow? --> Profile database queries, check indexes
+    ├── All endpoints slow? --> Check connection pool, memory, CPU
+    └── Intermittent slowness? --> Check for lock contention, GC pauses, external deps
+```
+
+### Step 2: Identify the Bottleneck
+
+Common bottlenecks by category:
+
+**Frontend:**
+
+| Symptom | Likely Cause | Investigation |
+|---------|-------------|---------------|
+| Slow LCP | Large images, render-blocking resources, slow server | Check network waterfall, image sizes |
+| High CLS | Images without dimensions, late-loading content, font shifts | Check layout shift attribution |
+| Poor INP | Heavy JavaScript on main thread, large DOM updates | Check long tasks in Performance trace |
+| Slow initial load | Large bundle, many network requests | Check bundle size, code splitting |
+
+**Backend:**
+
+| Symptom | Likely Cause | Investigation |
+|---------|-------------|---------------|
+| Slow API responses | N+1 queries, missing indexes, unoptimized queries | Check database query log |
+| Memory growth | Leaked references, unbounded caches, large payloads | Heap snapshot analysis |
+| CPU spikes | Synchronous heavy computation, regex backtracking | CPU profiling |
+| High latency | Missing caching, redundant computation, network hops | Trace requests through the stack |
+
+### Step 3: Fix the Bottleneck
+
+Fix the one thing Step 2 identified, nothing else. The anti-patterns below are the usual suspects; each entry gives the rule and the signature to recognize it, and links to a worked fix in [optimization-patterns.md](optimization-patterns.md). Open the one you need when you reach that code, not before.
+
+**Backend**
+
+- **N+1 queries.** One query per row is the most common backend bottleneck. Fetch the relation in the same query (join/include) instead of in the loop. [Pattern](optimization-patterns.md#n1-queries-backend).
+- **Unbounded data fetching.** Every list endpoint paginates with a limit and a stable order. [Pattern](optimization-patterns.md#unbounded-data-fetching).
+- **Queries that ignore their index.** "Add an index" is the guess; `EXPLAIN ANALYZE` is the measurement. A `Seq Scan` where you expected an index, a `rows=` estimate off by an order of magnitude, and a `Sort` node above the scan each call for a different fix; a bad `rows=` estimate means stale statistics, so run `ANALYZE` rather than adding an index. Index for the shape of the query (equality columns first, then the range or sort column). A plain index will not help a query on a low-selectivity dominant value (a partial index serves the rare value), a leading wildcard (needs trigram or full-text), or a function applied to the column (index the expression, as in `WHERE lower(email) = ?`), and every index taxes every write. Re-run the plan afterwards; an index that did not change it is a revert. [Pattern](optimization-patterns.md#queries-that-ignore-their-index).
+- **Connection pool exhaustion.** Signature: *every* endpoint slows at once, time is spent waiting for a connection rather than executing, and the database shows mostly idle sessions. One pool per process, sized so `instances × max` stays under the database's connection ceiling. Bigger is not faster; it relocates the queue to the database where it is harder to see. With unbounded instance counts (serverless, autoscaling), multiplex through a proxy (pgbouncer, RDS Proxy) instead of raising `max`. [Pattern](optimization-patterns.md#connection-pool-exhaustion).
+- **Missing caching.** Cache what is expensive to produce and read far more often than it changes; caching an already-fast query adds a network hop and a staleness bug in exchange for nothing. Pick the layer deliberately (in-process, shared, CDN). Every input that changes the response belongs in the key (tenant, locale, permissions, feature flags): a key that omits the viewer is how one user's data gets served to another. Choose one invalidation strategy (TTL, event or tag based, versioned keys) and state the acceptable staleness window explicitly. Guard hot keys against the stampede: serve stale while one request recomputes, or coalesce concurrent misses behind a single in-flight promise. Never cache what must be fresh (balances, permissions, inventory at checkout). [Pattern](optimization-patterns.md#missing-caching-backend); request coalescing, write strategies, and negative caching in `./performance-checklist.md`.
+
+**Frontend**
+
+- **Missing image optimization.** Every image declares `width` and `height` (CLS). The LCP image gets `fetchpriority="high"`, modern formats (AVIF, WebP) through `<picture>`, and `srcset`/`sizes` for resolution switching; below-the-fold images get `loading="lazy"` and `decoding="async"`. [Pattern](optimization-patterns.md#missing-image-optimization-frontend).
+- **Unnecessary re-renders.** An object or function created in render is a new reference every time and re-renders every child that receives it. Hoist constants; reserve `React.memo` and `useMemo` for work the profile shows is expensive, since overuse is its own cost. [Pattern](optimization-patterns.md#unnecessary-re-renders-react).
+- **Large bundle size.** Modern bundlers tree-shake ESM named imports on their own; the real gains are route-level code splitting and lazy-loading heavy, rarely-used features behind `Suspense`. Profile before changing import styles. [Pattern](optimization-patterns.md#large-bundle-size).
+
+### Step 4: Verify (Keep or Revert)
+
+A fix is a hypothesis until you re-measure. This step decides whether it survives.
+
+**Re-measure the way you measured the baseline:** same command, same conditions, same fixed budget (wall-clock, sample count, or request count). A baseline taken on a cold cache against a result taken on a warm one measures the cache, not your change.
+
+**Change one thing at a time.** Three optimizations landed together produce one number, and you cannot attribute it. If they must ship together, measure each in isolation first.
+
+**Beat the noise, not just the mean.** Repeat the measurement and compare the delta against run-to-run variance. A 3% gain inside ±5% variance is not a gain; it is a different sample.
+
+Then decide, strictly:
+
+| Result vs. baseline | Action |
+|---|---|
+| Past the threshold, tests green | **Keep.** Commit with the before/after numbers in the message. |
+| Within noise (no measurable change) | **Revert.** |
+| Worse | **Revert.** |
+| Improved, but a test went red | **Revert.** A regression wearing a win's clothing. |
+
+**"Neutral" is a revert, not a keep.** This is the step teams skip: the change is already written, throwing it away feels wasteful, so it lands unmeasured, and the codebase accretes complexity that never bought anything. Code you keep, you maintain forever. Make it pay for itself.
+
+**Correctness gates the metric.** The suite stays green *and* the number moves. An "optimization" that wins by dropping work the product needed (skipping a validation, caching something that must be fresh, removing an `await` that was load-bearing) is a regression, not a win.
+
+#### Log every attempt, including the reverted ones
+
+Reverted work leaves no trace in git history, which is exactly why the same dead idea gets tried again next quarter. Keep a short ledger so a discarded idea stays discarded:
+
+| Idea | Baseline → Result | Verdict | Why |
+|---|---|---|---|
+| Memoize the row component | INP 240ms → 235ms | reverted | Inside noise (±15ms). Rows weren't the bottleneck. |
+| Virtualize the list | INP 240ms → 90ms | kept | Long tasks gone from the trace. |
+| Preconnect to the API origin | LCP 2.8s → 2.8s | reverted | Already same-origin. |
+
+In ATW this ledger is the task's decision log (`decision-log.md`), one row per attempt, written as the `atw-performance` skill says. What matters is that the next person (or the next agent) reads it before proposing an experiment, and doesn't re-run one that already failed.
+
+### Step 5: Guard Against Regression
+
+Guard the metric the user actually feels, not every available number. Use the
+same LCP, INP, p95 latency, or other primary metric that justified the fix.
+
+Use two complementary layers when the surface is user-facing:
+
+- **Synthetic CI gate:** Catch reproducible regressions before merge with a
+  performance budget. Repeat noisy measurements or compare a median/trend so
+  normal run-to-run variance does not turn the gate into a flaky check.
+- **Field monitoring:** Alert on a meaningful p75 movement in RUM data. Use
+  attributed `web-vitals` data to locate the cause; treat CrUX's rolling window
+  as confirmation rather than an immediate alert.
+
+When either guard fires, return to Step 1 and establish a fresh baseline before
+proposing another fix.
+
+**Set budgets and enforce them:**
+
+```
+JavaScript bundle: < 200KB gzipped (initial load)
+CSS: < 50KB gzipped
+Images: < 200KB per image (above the fold)
+Fonts: < 100KB total
+API response time: < 200ms (p95)
+Time to Interactive: < 3.5s on 4G
+Lighthouse Performance score: ≥ 90
+```
+
+**Enforce in CI:**
+```bash
+# Bundle size check
+npx bundlesize --config bundlesize.config.json
+
+# Lighthouse CI
+npx lhci autorun
+```
+
+## See Also
+
+For detailed performance checklists, optimization commands, and anti-pattern reference, see `./performance-checklist.md`.
+
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "We'll optimize later" | Performance debt compounds. Fix obvious anti-patterns now, defer micro-optimizations. |
+| "It's fast on my machine" | Your machine isn't the user's. Profile on representative hardware and networks. |
+| "This optimization is obvious" | If you didn't measure, you don't know. Profile first. |
+| "Users won't notice 100ms" | Research shows 100ms delays impact conversion rates. Users notice more than you think. |
+| "The framework handles performance" | Frameworks prevent some issues but can't fix N+1 queries or oversized bundles. |
+| "The query is slow, add an index" | Read the plan first. The index may already exist and be unusable, and every index taxes writes forever. |
+| "Just cache it" | Caching an already-cheap call buys nothing and adds a staleness bug. Cache what is expensive *and* re-read far more than written. |
+| "Raise the pool size, we're running out of connections" | A pool bigger than the database can serve moves the queue somewhere less visible. Find what holds connections. |
+| "It didn't help much, but it doesn't hurt" | Neutral changes are a revert. You pay maintenance on them forever and got nothing back. |
+| "We already wrote it, may as well keep it" | Sunk cost. The measurement doesn't care how long the change took to write. |
+| "The improvement is obvious, no need to re-measure" | Then re-measuring is cheap and proves it. Unmeasured wins are how neutral complexity lands. |
+
+## Red Flags
+
+- Optimization without profiling data to justify it
+- N+1 query patterns in data fetching
+- An index added without a query plan before and after to justify it
+- A cache key that omits an input the response depends on (tenant, locale, viewer)
+- A cache with no stated staleness window and no invalidation strategy
+- Connection pool size raised in response to exhaustion, without finding what holds connections
+- List endpoints without pagination
+- Images without dimensions, lazy loading, or responsive sizes
+- Bundle size growing without review
+- No performance monitoring in production
+- `React.memo` and `useMemo` everywhere (overusing is as bad as underusing)
+- Optimizations kept without a re-measurement that justifies them
+- Several optimizations bundled into one measurement, so no single change can be attributed
+- A "win" that required a test to be changed, skipped, or deleted
+- The same failed optimization attempted more than once because nobody recorded the first attempt
+
+## Verification
+
+After any performance-related change:
+
+- [ ] Before and after measurements exist (specific numbers)
+- [ ] The result was re-measured the same way as the baseline (same command, same conditions)
+- [ ] The improvement exceeds run-to-run variance, not just the mean
+- [ ] Changes that didn't beat the baseline were reverted, not kept as neutral
+- [ ] Attempts are logged, kept and reverted alike, so a dead idea isn't re-run
+- [ ] The specific bottleneck is identified and addressed
+- [ ] Core Web Vitals are within "Good" thresholds
+- [ ] Bundle size hasn't increased significantly
+- [ ] No N+1 queries in new data fetching code
+- [ ] Any new index is justified by a query plan before and after, and its write cost was considered
+- [ ] Any new cache states what it keys on and how it goes stale
+- [ ] The measured user-facing metric has a synthetic budget or field monitor that can detect regression
+- [ ] Existing tests still pass (optimization didn't break behavior)

package/dist/templates/common/bundled-skills/atw-prototype/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: atw-prototype
-description: "构建一次性原型来解答设计问题。用于验证状态模型或业务逻辑是否合理、探索界面应该长什么样（先用文字比较几个风格方向，要看画面时再做成首屏并排对比，由用户选定），或把选定方向做成能完整点一遍、带业务逻辑的可交互原型。原型只用于做决定，不是正式实现；按选定方向做正式界面、精修和评审交给 atw-ui。"
+description: "构建一次性原型来解答设计问题。用于验证状态模型或业务逻辑是否合理、探索界面应该长什么样（先用文字比较几个风格方向，要看画面时再做成首屏并排对比，由用户选定），或把选定方向做成能完整点一遍、带业务逻辑的可交互原型。原型只用于做决定，不是正式实现；按选定方向做正式界面、精修和评审交给 atw-ui。设计方向还没定、想先验证状态模型或比一比几个风格方向时使用。"
 ---
 
 # Prototype
@@ -11,8 +11,8 @@ description: "构建一次性原型来解答设计问题。用于验证状态模
 
 先从用户的请求、相关代码判断要回答的是哪个问题；用户在场时可以直接问：
 
-- **“这套逻辑 / 状态模型对不对？”** → [LOGIC.md](LOGIC.md)。做一个可分享的单文件 HTML：自由操作的按钮加按标签页划分的引导演练，把纸面上难以推演的状态组合跑一遍，让不写代码的人也能自己操作。
-- **“这个界面应该长什么样？”** 或 **“这个页面用起来对不对？”** → [UI.md](UI.md)。分两段：先认品类、拆标杆，用文字写出三个风格明显不同的方向请用户选，用户要看画面时再把三个首屏放进对比页；需要时再把选定方向深化成带业务逻辑的可交互原型，业务逻辑按 LOGIC.md 的方式写成独立的纯模块。
+- **“这套逻辑 / 状态模型对不对？”** → [logic.md](logic.md)。做一个可分享的单文件 HTML：自由操作的按钮加按标签页划分的引导演练，把纸面上难以推演的状态组合跑一遍，让不写代码的人也能自己操作。
+- **“这个界面应该长什么样？”** 或 **“这个页面用起来对不对？”** → [ui.md](ui.md)。分两段：先认品类、拆标杆，用文字写出三个风格明显不同的方向请用户选，用户要看画面时再把三个首屏放进对比页；需要时再把选定方向深化成带业务逻辑的可交互原型，业务逻辑按 logic.md 的方式写成独立的纯模块。
 
 两个分支的产物差别很大，选错等于白做。问题确实模糊且用户不在时，按周边代码选：后端模块走逻辑，页面或组件走界面；并在原型顶部写明这个假设。
 

package/dist/templates/common/bundled-skills/atw-prototype/{LOGIC.md → logic.md}

@@ -11,7 +11,7 @@
 - “写接口之前，我想先感受一下它该长什么样。”
 - 任何想要**按按钮、看状态变化**的场景。
 
-如果问题是“这个界面应该长什么样”，分支选错了，改用 [UI.md](UI.md)。如果问题是“这个页面连同业务规则用起来对不对”，走 UI.md 的第二段：逻辑仍按本文件第 2 步写成纯模块，外面换成选定方向的设计界面。
+如果问题是“这个界面应该长什么样”，分支选错了，改用 [ui.md](ui.md)。如果问题是“这个页面连同业务规则用起来对不对”，走 ui.md 的第二段：逻辑仍按本文件第 2 步写成纯模块，外面换成选定方向的设计界面。
 
 ## 流程
 

package/dist/templates/common/bundled-skills/atw-prototype/references/design-direction.md

@@ -192,7 +192,7 @@
 
 ## 小样、选择与品味
 
-方向只做首屏，不一开始就做多套完整产品；轮次和数量见 [界面原型](../UI.md) 的“第一段：选方向”。
+方向只做首屏，不一开始就做多套完整产品；轮次和数量见 [界面原型](../ui.md) 的“第一段：选方向”。
 
 首屏选能暴露方向优缺点的那一页：含复杂表单的产品不能只做封面。
 

package/dist/templates/common/bundled-skills/atw-prototype/references/style-explorer.md

@@ -75,7 +75,7 @@ macOS/Linux 通常使用 `python3`，Windows 通常使用 `py -3`；执行前确
 
 生成器根据本轮项目和候选内容生成 `fingerprint`。候选内容变化后会形成新一轮存储身份，避免把旧选择误用于新作品。点“选择”时同时复制一句简短的文字：轮次、编号和方向名，有备注时再附一行，例如“<轮次>：选 03 <方向名>”，并在底部提示已复制的内容。改完备注后再点一次“已选择”重新复制；选另一个方向会直接替换当前选择。
 
-用户粘贴复制的结果或直接说出选择后，Agent 按轮次和编号对照当前 manifest，确认对应本轮，再把选择与备注更新到设计说明，回到 [界面原型](../UI.md) 第一段接着做。浏览器本地保存不代表已经写回项目文件，也不会自动向 Agent 发送消息。
+用户粘贴复制的结果或直接说出选择后，Agent 按轮次和编号对照当前 manifest，确认对应本轮，再把选择与备注更新到设计说明，回到 [界面原型](../ui.md) 第一段接着做。浏览器本地保存不代表已经写回项目文件，也不会自动向 Agent 发送消息。
 
 ## 检查实际结果
 

package/dist/templates/common/bundled-skills/atw-prototype/{UI.md → ui.md}

@@ -3,11 +3,11 @@
 界面原型分两段：
 
 - **第一段：选方向。** 先认品类、拆标杆，用文字写出三个风格和结构都明显不同的方向请用户选；用户想看实际画面时，再把三个方向各做成一张首屏放进同一个对比页挑，并说出具体喜欢和不喜欢哪里。
-- **第二段：深化成可交互原型。** 只在问题包含“用起来对不对”时才做：把选定方向做成完整页面，接上按 [LOGIC.md](LOGIC.md) 写的纯逻辑模块，让人能把真实业务流程完整点一遍。
+- **第二段：深化成可交互原型。** 只在问题包含“用起来对不对”时才做：把选定方向做成完整页面，接上按 [logic.md](logic.md) 写的纯逻辑模块，让人能把真实业务流程完整点一遍。
 
 两段的产物都是用来做决定的，不是正式代码。选定之后的正式界面由 atw-ui 按设计说明重新实现。
 
-如果问题只关于逻辑或状态、与外观无关，分支选错了，改用 [LOGIC.md](LOGIC.md)。
+如果问题只关于逻辑或状态、与外观无关，分支选错了，改用 [logic.md](logic.md)。
 
 ## 什么时候用
 
@@ -106,7 +106,7 @@
 
 ### 1. 先写逻辑模块
 
-按 [LOGIC.md](LOGIC.md) 第 2 步，把业务规则写成一个纯模块（reducer、状态机或纯函数），不碰 DOM。这部分以后能整体搬进正式代码，是第二段最值得保留的产物。
+按 [logic.md](logic.md) 第 2 步，把业务规则写成一个纯模块（reducer、状态机或纯函数），不碰 DOM。这部分以后能整体搬进正式代码，是第二段最值得保留的产物。
 
 ### 2. 选定方向做成完整页面
 
@@ -118,7 +118,7 @@
 
 ### 3. 加一个状态抽屉
 
-LOGIC.md 里的“当前状态面板”和“引导演练”放进一个可开关的抽屉，供不写代码的人逐步走查业务规则：
+logic.md 里的“当前状态面板”和“引导演练”放进一个可开关的抽屉，供不写代码的人逐步走查业务规则：
 
 - 抽屉视觉上明显不属于设计本身（例如高对比的面板），和浮动切换条一样，不参与设计评判。
 - 抽屉里保持朴素：标签式的状态字段、标出刚变化的部分、按场景划分的演练按钮；不加动画。