@dsalazardev/ai-hub-cli 0.0.0-stage → 0.2.0

package/skills/shared/parallel/evals/README.md

@@ -0,0 +1,62 @@
+# Eval harness — `parallel` skill
+
+Run by an **agent harness** (an LLM agent with the Skill tool), not a pure shell script.
+`cases.yaml` is the fixture; this README is the honest run procedure. Three things to measure:
+**triggering** (should fire), **anti-triggering** (must not fire), and **capability** (does the
+skill make the fan-out safer and faster).
+
+`parallel` is a process skill — it ships no `scripts/verify.sh`. It is judged on its safety rails
+(the independence test before dispatch, self-contained briefs, frozen contracts, the combined-suite
+reconcile gate), not on a deterministic command.
+
+## 1. Triggering accuracy
+
+For each prompt in `should_trigger` and `should_not_trigger`:
+
+1. Start a fresh agent session with the `parallel` skill available in the catalog, plus its named
+   routing siblings (`implement`, `tasks`, `worktrees`, `debug`) present but not the subject — so
+   routing is realistic.
+2. Feed the prompt verbatim. Do **not** hint that a skill exists.
+3. Observe whether the agent invokes the `parallel` skill.
+4. Run **3–5 trials** per prompt (LLM routing is stochastic); record the fire rate.
+
+Pass conditions:
+- Every `should_trigger` prompt fires `parallel` in **≥ 90%** of trials.
+- Every `should_not_trigger` prompt does **not** fire it in ≥ 90% of trials, and the agent prefers
+  the named `route_to` sibling. The boundaries to watch: `implement` (the serial/TDD work itself,
+  and any ordering-dependent task), `tasks` (makes the list, doesn't fan it out), `worktrees`
+  (isolation, not concurrency), and `debug` (the red post-merge seam). A near-miss leaking into
+  `parallel` — especially parallelizing tasks that share a file or have an ordering edge — is a
+  harder failure than a missed trigger, because it produces a merge race. Fix the description
+  boundary before shipping.
+
+## 2. Capability uplift (with vs without)
+
+For the `capability` scenario:
+
+1. **Without skill:** run the scenario in a clean session, no `parallel` skill loaded. Capture the
+   answer.
+2. **With skill:** run the same prompt with `parallel` (and the named `implement` sibling) loaded.
+3. Grade both against the scenario's `must_include` checklist — one point per bullet that is
+   *concretely* present (e.g. it actually catches that the two migration tasks share a file and
+   collapses them, not just the phrase "check independence").
+4. Use 3 trials each side; average the coverage.
+
+Pass conditions:
+- **With** the skill: `must_include` coverage **≥ 80%**.
+- **Measurable uplift:** with-skill coverage beats without-skill. The expected gaps in the
+  without-skill run are exactly the ones this skill exists to close: blindly parallelizing the two
+  tasks that share the orders migration (the trap), writing briefs that tell subagents to "coordinate"
+  instead of freezing the contract first, merging the fast units before the slow ones land, and
+  declaring done on green-in-isolation without ever running the combined suite.
+
+## What a failing eval tells you
+
+- Trigger misses → the description's "Use when…" triggers are too narrow; widen the phrasings
+  (including the Spanish and the non-obvious "concurrently / at the same time / reconcile" wordings).
+- Near-miss leaks → the boundary against `implement` (serial/dependent work), `worktrees`
+  (isolation), `tasks`, or `debug` is blurry in the description; sharpen the NOT clauses. The most
+  important one to keep tight is the independence boundary — the skill must *refuse* to fan out
+  coupled work.
+- Capability gaps → the SKILL.md body under-specifies the independence test, the contract-freezing
+  rule, the gather hold, or the combined-suite reconcile gate; tighten the relevant section.

package/skills/shared/parallel/evals/cases.yaml

@@ -0,0 +1,44 @@
+skill: parallel
+
+should_trigger:
+  - prompt: "These three modules don't depend on each other at all — the users repo, the invoices repo, and the docs. Fan them out across subagents instead of doing them one by one."
+    why: "Canonical fan-out: multiple disjoint units, no shared state, explicit ask to dispatch concurrently. Squarely this skill's partition→dispatch→gather→reconcile."
+  - prompt: "I've got a bunch of independent tasks in the plan. Split them across agents so they run at the same time, then merge the results."
+    why: "Independent tasks + 'run at the same time' + 'merge the results' is the full fan-out-and-reconcile shape this skill owns."
+  - prompt: "Estas tareas son independientes, no comparten ficheros ni estado. Repártelas en subagentes y hazlas a la vez."
+    why: "Spanish phrasing of the trigger, with the independence preconditions (no shared files/state) named explicitly — this skill's core gate."
+  - prompt: "Dispatch one agent per service to scaffold each one, they're in separate packages and share nothing. Gather what they each produce when they're done."
+    why: "One-subagent-per-unit on disjoint packages plus a gather step — the dispatch and gather phases of this skill, without naming it."
+  - prompt: "Can we parallelize the rest of the build? The auth module and the billing module are in different files and neither reads the other's output."
+    why: "Asks to parallelize while volunteering the independence evidence (different files, no output dependency) — the exact condition this skill checks before fanning out."
+  - prompt: "We have six unrelated cleanup tasks across six different files. Run them concurrently and reconcile at the end so the whole suite still passes."
+    why: "Many disjoint units + concurrency + reconcile-with-combined-suite — non-obvious phrasing that still lands on this skill's reconcile gate (green-together, not green-alone)."
+
+should_not_trigger:
+  - prompt: "First define the User type, then build the endpoint that returns a User. The endpoint needs the type to exist."
+    route_to: "implement"
+    why: "An explicit ordering dependency (second task needs the first's output) — that is a serial unit, handled inside implement, not fanned out. Parallelizing it would fail the independence test."
+  - prompt: "Break this approved plan into an ordered list of small tasks, each with a way to tell when it's done."
+    route_to: "tasks"
+    why: "Producing the ordered task list with done-checks is the tasks phase; parallel consumes that list to decide what can run together, it doesn't create it."
+  - prompt: "I want a clean isolated branch or worktree for this feature so it doesn't touch my current working tree. Set that up."
+    route_to: "worktrees"
+    why: "This is isolation (doing one thing cleanly), not concurrency (doing several at once). Wanting a clean room is worktrees, which parallel explicitly distinguishes itself from."
+  - prompt: "Two of my parallel branches merged and now the combined test suite is red somewhere in the seam. Find the root cause before I change anything."
+    route_to: "debug"
+    why: "Diagnosing a mysterious post-merge failure is the debug protocol (reproduce→isolate→fix); parallel hands the seam off to debug rather than guessing which unit broke."
+  - prompt: "Write each of these tasks test-first — failing test, make it pass, refactor — one commit per task."
+    route_to: "implement"
+    why: "The red→green→refactor TDD loop lives inside implement; parallel runs several such loops at once but never replaces the discipline within a single unit."
+
+capability:
+  - scenario: "User asks: 'I have four tasks left on the plan: (a) add the users repository, (b) add the invoices repository, (c) add a field to the orders migration, (d) add another field to the same orders migration. They feel independent — fan them out across subagents and merge when done.' (FastAPI stack noted in the plan; the register: technical in the profile.)"
+    must_include:
+      - "Runs the independence test pairwise and correctly identifies that (c) and (d) touch the SAME orders migration/file, so they are NOT independent and must be one serial unit — not two parallel units"
+      - "Partitions into a valid plan: (a) and (b) as disjoint parallel units, (c)+(d) collapsed into a single serial unit, with the partition written down before dispatch"
+      - "Writes one self-contained brief per parallel unit (scope/files owned, goal, done-check, the FastAPI testing constraint, report-back) that does not say 'see the other unit'"
+      - "Freezes any shared contract/type/schema in the serial spine BEFORE dispatching, rather than letting subagents coordinate it live"
+      - "Each unit keeps its own red→green→refactor (delegated to implement + the FastAPI testing reference); parallel does not relax the TDD discipline inside a unit"
+      - "Gathers ALL units, checks each against its done-check before merge, then reconciles: merges, resolves conflicts by hand, folds decision logs into .planning/history.md"
+      - "Runs the COMBINED suite across the merged result and refuses to call it done on green-in-isolation; if the seam is red, routes to debug rather than guessing"
+      - "Reports briefly in technical terms (the partition, frozen contracts, and each reconcile conflict with its fix, one line each) and hands the green result back to implement → verify"

package/skills/shared/performance/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: performance
+description: "Use when a page or interaction is slow for one user and the fix starts from a measurement — a failing Core Web Vital (LCP, INP, CLS), a heavy JS bundle, wasted re-renders, an over-broad client boundary: profile, attribute the cost to one phase, fix it, re-measure. NOT surviving concurrent load (that is `scaling`), NOT the slow query (that is `postgresdb`)."
+tags: [performance, core-web-vitals, lcp, inp, cls, bundle-size, profiling, react, web-vitals]
+recommends: [scaling, postgresdb, redis, nextjs, react, observability, monitoring]
+profiles: []
+origin: ai-hub
+---
+
+# Performance: make one thing fast
+
+Performance makes a single request, page, or interaction faster for one user. Scaling makes many requests survive at the same time. Different problem, different toolbox — if the system is fine for you and only bends under concurrent load, that is `../scaling/SKILL.md`, not this.
+
+The whole job in one line: **measure with a profiler → attribute the cost to one specific phase → apply the one fix that moves that phase → re-measure against a number.** Repeat until you clear the threshold, then stop.
+
+**Prime directive: no fix without a profile first.** A waterfall, a flame chart, a bundle treemap, or a field CWV number comes before you touch code. The fix you guess is almost never the fix the measurement points at, and a "fast" change that moves a phase nobody was waiting on is wasted work that you then have to maintain.
+
+Cross-reference, don't duplicate: the last column of the table below names where each deep fix lives. The one case it has no row for — you decided *what* to cache to cut a phase and now need that cache race-free — is `../redis/SKILL.md`.
+
+## Decision table — symptom to first move
+
+| Symptom | Metric / phase | First probe | First lever | Deep fix lives in |
+|---|---|---|---|---|
+| Slow load, hero appears late | LCP | Lighthouse + DevTools trace | attribute to a subpart, then fix that one | this skill / `../postgresdb/SKILL.md` if TTFB |
+| Janky scroll, laggy typing/click | INP | DevTools Performance trace (long-task bars) | break the >50 ms task, yield | this skill |
+| Layout jumps as it loads | CLS | Lighthouse layout-shift trace | reserve space (dimensions / aspect-ratio) | this skill |
+| "First Load JS is huge" | bundle bytes | `@next/bundle-analyzer` / `source-map-explorer` | kill/replace the heavy dep, then dynamic import | this skill |
+| Component re-renders constantly | render time | React DevTools Profiler ("why did this render") | fix the unstable ref / boundary | `../react/SKILL.md` for the pattern |
+| `'use client'` drags server work down | First Load JS | bundle analyzer server/client trace | push the boundary to a leaf | `../nextjs/SKILL.md` |
+| Slow **only** under concurrent load | throughput, not latency | load test | — not this skill — | `../scaling/SKILL.md` |
+| TTFB dominated by one query | server time | query plan / `EXPLAIN` | — not this skill — | `../postgresdb/SKILL.md` |
+
+## Step 0 — measure first: field vs lab
+
+You have two kinds of measurement and they answer different questions. Use both, in this order.
+
+- **Field data (CrUX, RUM via the `web-vitals` library) at the 75th percentile** tells you *what real users actually feel*. A metric passes when ≥75% of page views hit "good". This is the only number that matters for "is it actually a problem".
+- **Lab data (Lighthouse, the Chrome DevTools Performance trace)** tells you *why* — it reproduces one load under controlled conditions so you can read the waterfall and flame chart.
+
+**Rule: never optimize a lab number that no real user ever hits, and never report the mean — report the 75th percentile.** A lab Lighthouse run on a throttled cold cache can show an LCP your field p75 never sees; chasing it burns time on a phantom. Conversely a field INP failure with a clean lab run means you have not reproduced the slow interaction yet — go find it.
+
+The output of Step 0 is **one sentence naming the bottleneck**: "LCP is 3.8 s and 2.1 s of it is resource load delay because the hero image is lazy-loaded." Do not proceed without that sentence. Tool runbooks (Lighthouse CI flags, reading a flame chart, the Profiler workflow, wiring `web-vitals` for RUM) live in `references/profiling-playbook.md`.
+
+**Measurement honesty:** static source can identify a *plausible* bottleneck, never a measured LCP/INP/CLS, latency win or byte saving. If runtime/field data is unavailable, label the finding `POTENTIAL`, name the exact trace/benchmark needed, and make no numeric improvement claim. Do not turn code inspection into fictional telemetry.
+
+Keep one experiment card per change:
+
+```text
+metric + conditions | baseline distribution | one hypothesis/change | after distribution | keep/revert | next
+```
+
+Use the same device, data volume, cache state, build mode and sampling method before and after. Repeat enough runs to see ordinary variance; a one-off result inside that noise is neutral. Keep a change only when it moves the target beyond the noise without violating another budget. Revert a neutral or worse experiment with a targeted edit and preserve the card — failed attempts prevent the next person from paying for the same guess.
+
+## CWV "good" thresholds (field p75)
+
+| Metric | Good | Needs improvement | Poor |
+|---|---|---|---|
+| LCP | ≤ 2.5 s | 2.5–4.0 s | > 4.0 s |
+| INP | ≤ 200 ms | 200–500 ms | > 500 ms |
+| CLS | ≤ 0.1 | 0.1–0.25 | > 0.25 |
+
+INP replaced FID as a Core Web Vital in March 2024 and is still a CWV — it measures the full interaction-to-next-paint, so a fast event handler with a slow paint still fails. As of 2025, ~62% of mobile pages hit good LCP (up from 44% in 2022), and LCP remains the hardest CWV to pass and the most common overall bottleneck — so start there when the symptom is "slow load".
+
+## LCP — attribute to a subpart before fixing
+
+LCP is not one thing. It decomposes into four sequential phases, and **each phase has a different fix**. Attribute first, then fix only the dominant phase.
+
+| Subpart | What it is | The fix that moves it |
+|---|---|---|
+| TTFB | server + network to first byte | server work — punt to `../postgresdb/SKILL.md` (slow query) or `../scaling/SKILL.md` (under load); cache the response |
+| Resource load delay | gap between TTFB and the LCP resource *starting* to load | discoverability — `<link rel="preload">`, `fetchpriority="high"`, never lazy-load the hero |
+| Resource load duration | time to actually download the LCP resource | smaller/next-gen image, CDN, right dimensions, `priority` on `next/image` |
+| Element render delay | resource downloaded but not yet painted | unblock the main thread / render-blocking CSS/JS, font readiness |
+
+A text-node LCP rendered in a system font has zero load delay and zero load duration — its budget is all TTFB and render delay, so don't go hunting for an image to preload.
+
+The single most common LCP mistake is lazy-loading the largest element. Make it eager and high priority:
+
+```html
+<!-- Bad: the hero is the LCP element and you just deferred it -->
+<img src="/hero.webp" loading="lazy" alt="Product" />
+
+<!-- Good: eager + high priority + reserved dimensions (also kills CLS) -->
+<link rel="preload" as="image" href="/hero.webp" fetchpriority="high" />
+<img src="/hero.webp" fetchpriority="high" width="1200" height="630" alt="Product" />
+```
+
+```tsx
+// Next.js: `priority` sets fetchpriority=high and disables lazy-loading for the LCP image
+import Image from "next/image";
+<Image src="/hero.webp" width={1200} height={630} priority alt="Product" />;
+```
+
+## INP — kill the long task
+
+INP is dominated by **long tasks**: any main-thread task over **50 ms** blocks every interaction for its full duration. The fix is to break long work into chunks under 50 ms and yield to the main thread between them so a queued click or keypress can run.
+
+```ts
+// Bad: one 400ms loop blocks every click/keypress while it runs
+function processAll(items: Item[]) {
+  for (const item of items) heavyWork(item); // one long task
+}
+
+// Good: chunk + yield. scheduler.yield() resumes at the FRONT of the queue,
+// so your continuation isn't starved behind newly-queued work.
+async function processAll(items: Item[]) {
+  for (let i = 0; i < items.length; i++) {
+    heavyWork(items[i]);
+    if (i % 50 === 0 && "scheduler" in globalThis) {
+      await (globalThis as any).scheduler.yield();
+    }
+  }
+}
+```
+
+Other INP levers, in order of payoff:
+
+- **Move third-party JS off the main thread** (analytics, chat widgets, tag managers) — defer, load on interaction, or sandbox in a worker. Third-party scripts are the usual hidden long-task source.
+- **Defer non-urgent handler work.** Do the visible state update now; push the expensive recompute behind `requestIdleCallback`, a debounce, or `startTransition`.
+- **Measure the actual interaction** — the field INP failure names *which* interaction; reproduce it in a DevTools trace and read the long-task bar, don't guess.
+
+## CLS — reserve the space
+
+CLS comes from space that was not reserved before content arrived: images/video/ads/embeds without dimensions, content injected above existing content, and font swaps (FOUT). Fix by reserving the box up front.
+
+```html
+<!-- Bad: no dimensions, image reflows everything below it on load -->
+<img src="/card.webp" alt="" />
+
+<!-- Good: explicit box, zero shift -->
+<img src="/card.webp" width="400" height="300" alt="" />
+```
+
+```css
+/* Reserve space for ratio-based media and swap fonts without reflow */
+.media { aspect-ratio: 16 / 9; }                 /* box exists before load */
+@font-face { font-family: Inter; font-display: optional; size-adjust: 100%; }
+```
+
+Rules: give every image/embed explicit `width`/`height` or an `aspect-ratio`; render skeleton boxes the size of the real content; never insert banners/notices above content the user is already reading (push them below or overlay); use `font-display: optional` (or `swap` + `size-adjust`) so a font swap doesn't reflow text.
+
+## Bundle size — analyze before you cut
+
+Never guess what's heavy. Generate a treemap, read it, then cut the biggest box.
+
+```bash
+# Next.js: interactive treemap with server/client import tracing (Turbopack module graph)
+ANALYZE=true npm run build      # with @next/bundle-analyzer wired in next.config
+
+# Any webpack/Vite build: attribute bytes back to source via source maps
+npx source-map-explorer 'dist/**/*.js'
+```
+
+Levers in order of payoff:
+
+1. **Kill or replace the heavy dependency.** The treemap usually shows one or two boxes dwarfing everything (a date library, an icon set, a charting lib). Replace with a lighter one or a few lines of your own.
+2. **Dynamic `import()` for non-critical UI.** Modals, editors, charts, anything below the fold or behind an interaction loads on demand instead of in First Load JS.
+3. **Fix tree-shaking — stop importing the whole library for one function.** `import _ from "lodash"` pulls the entire library; import the one function (or use the native equivalent).
+
+```tsx
+// Bad: whole library in the initial bundle for one helper
+import _ from "lodash";
+const fn = _.debounce(save, 300);
+
+// Good: named import (tree-shakeable) — or just write the 6-line debounce
+import debounce from "lodash-es/debounce";
+const fn = debounce(save, 300);
+```
+
+```tsx
+// Bad: heavy editor in First Load JS even though it's behind a button
+import { RichEditor } from "@org/rich-editor";
+
+// Good: split it out, load on demand
+import dynamic from "next/dynamic";
+const RichEditor = dynamic(() => import("@org/rich-editor"), { ssr: false });
+```
+
+## Render cost — React 19, the compiler, and the boundary
+
+**React 19 with the React Compiler auto-memoizes**, so blanket defensive `useMemo`/`useCallback`/`memo` is now an anti-pattern, not a best practice — it adds noise and the compiler already handles the common cases. Manual memo is the exception, and you justify it with a profile.
+
+- Profile with the **React DevTools Profiler**: record an interaction, find the component that re-rendered, read "why did this render" and its render time.
+- **The 16 ms rule:** one frame at 60 fps is ~16 ms. If a manual memo saves less than that, skip it — you can't see it and you're paying for the cache.
+- The compiler **cannot** fix a new object/array/function reference created in render and passed as a prop — that's a fresh identity every time. Hoist it or derive it stably; that's the real fix, not wrapping the consumer in `memo`.
+
+**React Server Components boundary discipline.** React Server Components ship zero JS for non-interactive trees; teams report 50–70% First-Load-JS cuts from full React Server Components adoption. The `'use client'` directive is a *boundary*: everything imported below it becomes client code. So push interactivity into the smallest leaf component and keep data fetching and layout on the server.
+
+```tsx
+// Bad: 'use client' at the top of the route — the whole tree ships to the browser
+"use client";
+export default function ProductPage({ data }) {
+  /* layout, data display, and one tiny button all client-side */
+}
+
+// Good: server component holds data/layout; only the interactive leaf is a client component
+export default function ProductPage({ data }) {       // server: zero JS
+  return (
+    <article>
+      <ProductDetails data={data} />                  {/* server */}
+      <AddToCartButton id={data.id} />                {/* the only 'use client' file */}
+    </article>
+  );
+}
+```
+
+Use **streaming SSR with `<Suspense>`** to flush the static shell immediately and stream slow subtrees in parallel — multiple independent boundaries stream concurrently, cutting time-to-first-paint when one section is data-bound. The canonical App-Router data and component patterns are `../nextjs/SKILL.md` and `../react/SKILL.md`; bring the perf loop here, take the idioms there.
+
+## Anti-patterns
+
+| Anti-pattern | Why it's wrong | Do instead |
+|---|---|---|
+| Optimizing on a hunch, no profile | you fix a phase nobody waits on | measure → attribute → fix the dominant phase |
+| Chasing a lab score no real user hits | lab cold-cache LCP ≠ field p75 | optimize the field 75th-percentile number |
+| Reporting the mean, not p75 | the average hides the tail users feel | always read/report the 75th percentile |
+| Blanket `useMemo`/`useCallback` in React 19 | the compiler already memoizes; you add noise | memo only what the Profiler proves >16 ms |
+| Lazy-loading the LCP / hero image | you defer the very element LCP measures | `priority` / `fetchpriority=high`, eager |
+| `import _ from "lodash"` for one function | the whole library lands in First Load JS | named import or a few lines of your own |
+| `'use client'` at the top of the tree | the entire subtree ships to the browser | push the boundary to the interactive leaf |
+| Images/embeds with no reserved space | content reflows on load → CLS | explicit width/height or `aspect-ratio` |
+| Micro-optimizing a non-bottleneck phase | effort moves a number off the critical path | fix only the phase the trace points at |
+| "Done" without re-measuring | the fix may not have moved the metric | re-measure against the threshold, then stop |
+| Reporting source-only review as a measured win | no trace/field/benchmark ran, so the number is invented | label POTENTIAL and name the measurement |
+| Changing three levers in one experiment | you cannot attribute the result or reuse the learning | one hypothesis/change per card, then re-measure |
+| Keeping a neutral optimization | complexity rose but the target did not beat normal variance | targeted revert; retain the failed-experiment record |
+
+## Stop rule
+
+You are done when the **field 75th percentile clears the "good" threshold** (LCP ≤ 2.5 s, INP ≤ 200 ms, CLS ≤ 0.1) and your bundle is under its budget — re-measure to confirm, then stop. Going from "good" to "slightly better good" is gold-plating: it costs maintenance and moves a number no user notices. Commit the threshold as a budget so it can't silently regress (`scripts/verify.sh` lints that budget; see `references/profiling-playbook.md` for the field-RUM wiring that keeps the p75 honest in production).

package/skills/shared/performance/evals/README.md

@@ -0,0 +1,3 @@
+# Evals — performance
+
+These cases are routing and trigger fixtures, not an automated test harness. `should_trigger` lists prompts the `performance` description and body must claim — including the non-obvious ones (whole-library import, a `'use client'` boundary shipping the server tree) and the Catalan/Spanish phrasings. `should_not_trigger` lists near-miss prompts that belong to a real sibling, each tagged with the `route_to` id it should defer to (`scaling`, `postgresdb`, `redis`, `nextjs`, `react`). `capability` is one "slow product page" scenario with a `must_include` rubric covering the measure → attribute → fix → re-measure loop. To run them, read each prompt against `../SKILL.md` and confirm by hand that the triggers fire, the non-triggers route to the named sibling rather than being grabbed, and a real answer to the capability scenario hits every rubric line — or feed this file to the repo's eval runner if one is present. The committed performance budget the skill tells you to author is checked separately by `../scripts/verify.sh`.

package/skills/shared/performance/evals/cases.yaml

@@ -0,0 +1,49 @@
+skill: performance
+
+should_trigger:
+  - prompt: "My LCP is 4.2s on mobile in Search Console — how do I fix it?"
+    why: "Direct Core Web Vitals failure at the field level; the canonical reason to reach for performance and attribute LCP to a subpart."
+  - prompt: "First Load JS is 800KB — what's making the bundle so big?"
+    why: "Bundle-size analysis; the body's analyze-before-cut loop with the treemap is exactly this."
+  - prompt: "Typing in this search box feels laggy and our INP is failing."
+    why: "INP / long-task; non-obvious because it reads as a UI complaint, but it's the >50ms task model."
+  - prompt: "The page content jumps around while it loads and it's annoying."
+    why: "CLS described by symptom without naming the metric — performance reserves space to fix it."
+  - prompt: "We import all of lodash just to use debounce — is that why the bundle is huge?"
+    why: "Non-obvious tree-shaking / whole-library trap; a named anti-pattern in the body."
+  - prompt: "A 'use client' at the top of our route is shipping the whole server tree to the browser — how do we cut First Load JS?"
+    why: "Non-obvious React Server Components boundary discipline; performance owns the measure-cut loop, framework idioms defer to nextjs."
+  - prompt: "La pàgina carrega molt lenta i no passa els Core Web Vitals, per on començo?"
+    why: "Catalan — slow load failing CWV, the heart of the skill (measure field p75 first)."
+  - prompt: "El bundle pesa demasiado, hay que analizarlo antes de tocar nada."
+    why: "Spanish — analyze-before-cutting the bundle, the skill's prime directive applied to bundle size."
+
+should_not_trigger:
+  - prompt: "Will the site survive the launch traffic spike on Monday?"
+    route_to: scaling
+    why: "Concurrency / capacity survival for many requests at once, not single-request speed."
+  - prompt: "This query does a sequential scan in production — how do I index it?"
+    route_to: postgresdb
+    why: "Query plan / index fix itself; performance only attributes 'TTFB is the bottleneck' and names the query."
+  - prompt: "Our cache stampedes the origin on every deploy — make it single-flight."
+    route_to: redis
+    why: "Cache correctness / race-freedom; performance decides what to cache, redis makes it race-free."
+  - prompt: "What's the idiomatic way to structure data fetching in the App Router?"
+    route_to: nextjs
+    why: "Framework-canonical data pattern, not the cross-cutting measure-fix-remeasure loop."
+  - prompt: "When should I reach for useReducer vs useState in this component?"
+    route_to: react
+    why: "Idiomatic React state design, not a profiled render-cost problem with a measured target."
+
+capability:
+  - scenario: "A product page has a field LCP of 3.8s and First Load JS of 600KB on mobile. Make it fast."
+    must_include:
+      - "Measures first — reads field CWV at the 75th percentile (CrUX/RUM) for the real problem, then a Lighthouse/DevTools lab trace for the why, before changing code."
+      - "Attributes LCP to a specific subpart (TTFB / load delay / load duration / render delay) and names the dominant one in one sentence before fixing."
+      - "Names a concrete LCP fix tied to that subpart — e.g. preload + fetchpriority=high / next-image priority / stop lazy-loading the hero — not a generic 'optimize images'."
+      - "Analyzes the bundle with a named tool (@next/bundle-analyzer or source-map-explorer) and reads the treemap before cutting anything."
+      - "Proposes a concrete bundle cut — replace/remove a heavy dep, dynamic import() for non-critical UI, or fix a whole-library import — in payoff order."
+      - "Does NOT blanket-memoize React components (notes React 19 compiler auto-memoizes) and does not guess fixes without the profile."
+      - "Re-measures against the numeric targets (LCP ≤ 2.5s field p75 and a bundle budget) and stops at 'good' rather than gold-plating."
+      - "Never reports source inspection as a measured result; without runtime/field data it labels findings POTENTIAL and names the exact trace or benchmark required."
+      - "Records baseline conditions and variance, changes one lever, re-measures under the same conditions, and targeted-reverts neutral or worse experiments while preserving the failed-attempt record."

package/skills/shared/performance/references/profiling-playbook.md

@@ -0,0 +1,54 @@
+# Profiling playbook
+
+Tool-specific runbooks the SKILL body points to. Pick the tool that matches the phase you're attributing; each one answers a different question.
+
+## Field data — the only number that decides "is it a problem"
+
+Field = real users, 75th percentile. Two sources:
+
+- **CrUX / PageSpeed Insights** — `https://pagespeed.web.dev/` gives you the field CWV for any public URL (28-day rolling p75) plus a lab Lighthouse run side by side. Read the field section first; the lab section is for the *why*.
+- **RUM via the `web-vitals` library** — for your own real traffic, especially routes CrUX doesn't have enough data for.
+
+```ts
+// web-vitals: report each metric to your analytics endpoint (field RUM)
+import { onLCP, onINP, onCLS } from "web-vitals";
+
+function send(metric: { name: string; value: number; rating: string }) {
+  navigator.sendBeacon("/rum", JSON.stringify(metric));
+}
+onLCP(send);
+onINP(send);
+onCLS(send);
+```
+
+Aggregate these at the 75th percentile per route. The mean lies — a p50 of 1.5 s with a p75 of 4 s is a failing route the average calls fine. Dashboards/alerting for this stream are `../../monitoring/SKILL.md` / observability's job; here you only need the p75 to know whether you've cleared the threshold.
+
+## Lighthouse — the lab "why" for load
+
+- Run from Chrome DevTools → Lighthouse panel, or CLI `npx lighthouse <url> --view`. Use **mobile + simulated throttling** (the default) — desktop hides the bottleneck most users hit.
+- In CI, gate a build with Lighthouse CI (`lhci autorun`) and an assertion budget so a regression fails the PR. Treat the budget file as the source of truth (see `verify.sh`).
+- Lighthouse is a single throttled lab load. If its LCP is far worse than field p75, trust the field — don't chase the lab phantom.
+
+## Chrome DevTools Performance trace — read the flame chart
+
+1. DevTools → Performance → record, reload or perform the interaction, stop.
+2. **LCP/CLS markers** sit on the Timings track — the LCP marker tells you the element and the timestamp; hover for the subpart breakdown (TTFB / load delay / load duration / render delay).
+3. **Main-thread track** is the flame chart. Wide bars = expensive functions. Bars flagged with a red corner are **long tasks (>50 ms)** — these are your INP suspects. Click one to see the call stack and which script owns it (often third-party).
+4. Attribute before fixing: name the dominant subpart (LCP) or the owning script (INP). One sentence, then fix that one thing.
+
+## React DevTools Profiler — re-render cost
+
+1. Install React DevTools, open the **Profiler** tab, record an interaction, stop.
+2. The flamegraph colors components by render time; the ranked chart lists the slowest. Click a component → **"Why did this render?"** shows hooks/props that changed.
+3. Apply the **16 ms rule**: a manual `useMemo`/`useCallback` is only worth it if it saves more than one 60 fps frame (~16 ms). React 19's compiler already memoizes the common cases — don't add manual memo the Profiler can't justify.
+4. The usual real cause is an unstable reference (new object/array/function created in render and passed as a prop). The compiler can't fix that — hoist or stabilize it; don't wrap the child in `memo` to paper over it.
+
+## Bundle treemap — what's actually heavy
+
+- **Next.js:** wire `@next/bundle-analyzer` into `next.config`, then `ANALYZE=true npm run build`. It opens an interactive treemap and (current Next) uses the Turbopack module graph to trace which `'use client'` boundary pulled a module into the client bundle.
+- **Any webpack/Vite build:** `npx source-map-explorer 'dist/**/*.js'` attributes bytes back to source files via source maps.
+- Reading it: box area = bytes. One or two boxes usually dwarf the rest — that's your first cut (replace the dep). Then look for whole-library imports (a giant box for a lib you use one function from) and for heavy UI that could be a dynamic `import()`.
+
+## Order of attack
+
+Field p75 says *which metric* fails → lab trace says *which phase/script* → fix that one phase → re-measure field p75. Stop at "good".

package/skills/shared/performance/scripts/verify.sh

@@ -0,0 +1,94 @@
+#!/usr/bin/env bash
+# verify.sh — budget-validity gate for the performance skill's artifacts.
+#
+# The skill tells you to commit a performance budget (a Core Web Vitals target
+# + a bundle-size budget) so the thresholds can't silently drift. This script
+# statically lints any such budget file it finds. It does NOT run a live
+# Lighthouse audit — that needs a real URL and a browser and is non-hermetic;
+# the behavioral rigor lives in ../evals/. This only checks the committed
+# artifact.
+#
+# Read-only: it never writes, never makes a network request.
+# Exits 0 on a clean/empty target (no budget file found is NOT a failure).
+# Exits 1 only when a budget file that DOES exist is malformed or carries a
+# Core Web Vitals threshold that contradicts the canonical "good" numbers:
+#   LCP 2500 ms, INP 200 ms, CLS 0.1.
+set -euo pipefail
+
+SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+fail=0
+checked=0
+
+# Canonical CWV "good" thresholds (field 75th percentile).
+LCP_MS=2500
+INP_MS=200
+CLS=0.1
+
+have() { command -v "$1" >/dev/null 2>&1; }
+
+# Extract a numeric value for a key from a JSON file. Prefer jq; fall back to a
+# grep/sed scrape so the check works with zero dependencies.
+json_num() {
+  local file="$1" key="$2"
+  if have jq; then
+    jq -r ".. | objects | .\"$key\"? // empty | select(type==\"number\")" "$file" 2>/dev/null | head -n1
+  else
+    grep -Eo "\"$key\"[[:space:]]*:[[:space:]]*[0-9.]+" "$file" 2>/dev/null \
+      | head -n1 | grep -Eo '[0-9.]+$'
+  fi
+}
+
+# A budget is "LCP-shaped" if it mentions LCP at all; only then do we lint it.
+looks_like_budget() {
+  grep -Eqi '"?lcp"?|core[ _-]?web[ _-]?vitals|first[ _-]?load[ _-]?js|bundle' "$1" 2>/dev/null
+}
+
+check_budget() {
+  local file="$1"
+  looks_like_budget "$file" || return 0
+  checked=$((checked + 1))
+
+  # Must be valid JSON when jq is available.
+  if have jq && ! jq empty "$file" >/dev/null 2>&1; then
+    echo "FAIL  $file (invalid JSON)"
+    fail=1
+    return 0
+  fi
+
+  local missing=() bad=()
+  local lcp inp cls
+  lcp="$(json_num "$file" lcp)"
+  inp="$(json_num "$file" inp)"
+  cls="$(json_num "$file" cls)"
+
+  [ -n "$lcp" ] || missing+=("lcp")
+  [ -n "$inp" ] || missing+=("inp")
+  [ -n "$cls" ] || missing+=("cls")
+
+  # A budget threshold must not be LOOSER than the canonical "good" number.
+  [ -n "$lcp" ] && awk "BEGIN{exit !($lcp > $LCP_MS)}" && bad+=("lcp=$lcp ms looser than $LCP_MS")
+  [ -n "$inp" ] && awk "BEGIN{exit !($inp > $INP_MS)}" && bad+=("inp=$inp ms looser than $INP_MS")
+  [ -n "$cls" ] && awk "BEGIN{exit !($cls > $CLS)}"   && bad+=("cls=$cls looser than $CLS")
+
+  if [ "${#missing[@]}" -ne 0 ] || [ "${#bad[@]}" -ne 0 ]; then
+    echo "FAIL  $file"
+    [ "${#missing[@]}" -ne 0 ] && printf '      missing metric: %s\n' "${missing[@]}"
+    [ "${#bad[@]}" -ne 0 ]     && printf '      drifted: %s\n' "${bad[@]}"
+    fail=1
+  else
+    echo "OK    $file (LCP/INP/CLS budget within canonical good thresholds)"
+  fi
+}
+
+# Lint every JSON budget candidate under the skill dir (bash 3.x safe — no mapfile).
+while IFS= read -r f; do
+  [ -n "$f" ] || continue
+  check_budget "$f"
+done < <(find "$SKILL_DIR" -type f \( -name 'budget*.json' -o -name '*budget.json' \
+            -o -name '.lighthouserc.json' -o -name 'perf-budget.json' \) 2>/dev/null || true)
+
+if [ "$checked" -eq 0 ]; then
+  echo "No performance budget file found — nothing to verify (clean)."
+fi
+
+exit "$fail"