@damiangilgonzalez/harness 1.3.7

package/skills/people-ops/evals/cases.yaml

@@ -0,0 +1,43 @@
+skill: people-ops
+
+should_trigger:
+  - prompt: "Our new engineer starts Monday — build me an onboarding plan with a 30/60/90."
+    why: Core onboarding artifact; offer is signed and the ramp plan is the central output.
+  - prompt: "Draft a remote-work policy for our handbook."
+    why: Core policy authoring — a handbook section with the privilege-not-right framing.
+  - prompt: "The offer's signed, what do I actually need to have ready before day one?"
+    why: Non-obvious — no word "onboarding"; this is the preboarding window plus the Day-1 legal clock.
+  - prompt: "Plan de onboarding y un calendario de 1:1s para el nuevo fichaje."
+    why: Spanish; combines onboarding with the operating rhythm (weekly 1:1s).
+  - prompt: "Someone's leaving next week — what's our offboarding checklist?"
+    why: The exit moment — same-day access revocation, knowledge handoff, exit conversation.
+  - prompt: "This employee handbook reads like a contract — can you fix it?"
+    why: Policy audit; the at-will / not-a-contract guardrail is exactly people-ops territory.
+
+should_not_trigger:
+  - prompt: "Write a job description and screen these 40 candidates."
+    route_to: hiring
+    why: Sourcing and screening happen before acceptance; people-ops starts at offer-signed.
+  - prompt: "Document our deployment release process step by step."
+    route_to: sop-builder
+    why: A generic operational procedure, not a people policy.
+  - prompt: "Draft the actual employment contract and NDA for this hire."
+    route_to: contracts
+    why: Legally binding instruments; the handbook people-ops writes explicitly is not a contract.
+  - prompt: "Write our employee-data privacy notice and GDPR record-handling policy."
+    route_to: gdpr-privacy
+    why: A statutory data-protection regime, not an internal HR policy.
+
+capability:
+  - scenario: >
+      A 12-person startup just hired its first non-founder employee, starting Monday.
+      Produce the onboarding plan plus a remote-work policy section for the new handbook.
+    must_include:
+      - A 30/60/90 plan framed learn → contribute → own
+      - Explicit manager actions (Day-1 task, week-1 goals conversation, buddy), not only HR tasks
+      - Paperwork placed in preboarding, not on Day 1
+      - The US I-9 / E-Verify timeline WITH a jurisdiction-confirm flag (this is US; EU/UK differ; many are not at-will)
+      - Remote policy framed "privilege, not a right" with concrete conditions (secured devices, core-hours availability, dedicated workspace)
+      - An at-will + "this is not a contract" disclaimer with a signed acknowledgment
+      - A weekly 1:1 set up from week one
+      - Does NOT write the employment contract itself; defers it to contracts

package/skills/people-ops/references/templates.md

@@ -0,0 +1,129 @@
+# people-ops templates
+
+Copy-ready, fill-in material offloaded from `SKILL.md`. This is lookup/fill-in
+content, not reasoning — adapt the bracketed `[...]` parts. Every legal item
+below assumes **US at-will** unless you change it; confirm your jurisdiction
+before sending (EU/UK and most countries are not at-will).
+
+## Preboarding checklist (days before start)
+
+Paperwork lives here, not on Day 1.
+
+- [ ] Send offer paperwork + employment forms for e-signature (route mechanics to `../e-signature/SKILL.md`)
+- [ ] I-9 Section 1 instructions (employee completes on/before Day 1)
+- [ ] Tax/benefits enrollment via self-service portal
+- [ ] Order equipment (laptop, peripherals, phone) — confirm delivery before start date
+- [ ] Request account provisioning: email, SSO, chat, repos, project tool, calendar
+- [ ] Assign a **buddy** (peer, not the manager); brief them on the role
+- [ ] Manager drafts the first concrete Day-1 task and the 30/60/90 goals
+- [ ] Add the new hire to the team calendar, on-call/rota exclusions, mailing lists
+- [ ] Schedule the recurring **weekly 1:1** starting week one
+- [ ] Welcome note + Day-1 logistics (where/when, dress, lunch plan)
+
+## Day-1 checklist (the person starts)
+
+No form marathon. Access works, equipment is ready, people are introduced.
+
+- [ ] Accounts live and tested (email, SSO, chat, repos) — verify *before* they arrive
+- [ ] Equipment set up; can log in on first try
+- [ ] Manager welcome + the first real task (not "settle in")
+- [ ] Team intros + buddy introduced in person/call
+- [ ] Tour of the docs: where the handbook, the wiki, the on-call live
+- [ ] I-9 Section 1 confirmed complete; calendar I-9 Section 2 (employer, within 3 business days)
+- [ ] E-Verify case if used (by the 3rd business day)
+- [ ] Confirm the week-1 goals conversation is on the calendar
+
+## 30/60/90 plan (manager + new-hire columns)
+
+Framed learn → contribute → own. Fill the bracketed cells per role.
+
+| Window | Theme | New hire does | Manager does |
+|---|---|---|---|
+| Days 1–30 | **Learn** | Tools, product/codebase, team norms; ship one small thing | Day-1 task; week-1 goals talk; weekly 1:1; check buddy is working |
+| Days 31–60 | **Contribute** | Owns a small recurring responsibility; gives process feedback | Stretch the scope; first written check-in; remove blockers |
+| Days 61–90 | **Own** | Carries one deliverable end-to-end | 90-day review; confirm ramp; set next-quarter goals |
+
+Success at 90 days = `[the one deliverable they now own]`.
+
+## Minimum-viable handbook — section list + drafting note
+
+The short list a small company actually needs. One line each.
+
+1. **Equal opportunity / anti-harassment** — state the protected classes and the report channel; name who receives reports.
+2. **Attendance + work hours** — core hours, time-off request flow, expected response norms.
+3. **PTO + sick leave** — accrual or unlimited, how to request, carryover/cap; sick leave per local statute.
+4. **Confidentiality** — what counts as confidential; survives employment; ties to the NDA in `../contracts/SKILL.md`.
+5. **Technology / acceptable use** — approved devices, security baseline, corporate tools vs personal apps.
+6. **Remote / hybrid** — privilege not right; dedicated workspace, secured company devices, core-hours availability.
+7. **Disciplinary process** — describe it as **discretionary**, never a mandatory fixed ladder.
+8. **Acknowledgment** — signed, dated, versioned; re-sign on material change.
+
+## At-will + not-a-contract + acknowledgment boilerplate
+
+> **Jurisdiction caveat:** US at-will only. Most countries are not at-will; in those
+> jurisdictions this language is wrong and may be unenforceable. Have a licensed
+> attorney review before use — you draft and flag, a lawyer signs off
+> (`../contracts/SKILL.md`).
+
+```text
+At-will employment. Your employment with [Company] is at-will. Either you or
+[Company] may end the employment relationship at any time, with or without
+cause and with or without notice. No one other than [the CEO], in a signed
+writing, may change the at-will nature of employment.
+
+Not a contract. This handbook is a guide to current policies and benefits. It
+is not a contract of employment and does not promise employment for any
+specific period. [Company] may add to, change, or withdraw any policy at any
+time, with notice where required by law.
+
+Discipline. Where progressive discipline is described, it is at [Company]'s
+discretion and any step may be skipped. Nothing here requires a fixed sequence
+before termination.
+```
+
+```text
+Acknowledgment (employee signs and returns)
+
+I have received and read the [Company] Employee Handbook, version [X.Y], dated
+[YYYY-MM-DD]. I understand my employment is at-will and that this handbook is
+not a contract. I understand policies may change and that I may be asked to
+re-acknowledge on material changes.
+
+Name: __________________   Signature: __________________   Date: __________
+```
+
+## 1:1 agenda template (weekly, 15–30 min)
+
+Coaching, not status. The report owns the agenda; you own showing up.
+
+```text
+1:1 — [name] — [date]
+1. Wins since last time
+2. Blockers / where you're stuck (manager removes blockers)
+3. Growth — skills, scope, the thing you want next
+4. Feedback both ways — for the report, and ask for feedback on yourself
+5. Action items (owner + date)
+```
+
+## Quarterly review template
+
+```text
+Quarterly review — [name] — [Q# YYYY]
+- Goals this quarter (2 objectives × 3–4 key results): status per KR
+- What went well
+- What to adjust
+- Growth / development focus next quarter
+- Next-quarter goals (set together)
+- Compensation/role notes (if applicable)
+```
+
+## Offboarding checklist (someone is leaving)
+
+- [ ] **Revoke access same-day** — SSO, email, chat, repos, third-party tools, VPN, building badge
+- [ ] Transfer ownership of accounts, files, calendars, on-call, vendor logins
+- [ ] **Knowledge handoff** — what only this person knew, written down before they go
+- [ ] Return equipment; account for company property
+- [ ] Final pay, accrued PTO payout, benefits/COBRA notices per local law
+- [ ] **Exit conversation** — why they're leaving (the retention data you can't buy)
+- [ ] Update headcount + who-owns-what; reassign their responsibilities
+- [ ] Employee-record retention/deletion per `../gdpr-privacy/SKILL.md`

package/skills/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: risco
+---
+
+# 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`.
+
+**RSC boundary discipline.** React Server Components ship zero JS for non-interactive trees; teams report 50–70% First-Load-JS cuts from full RSC 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/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/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 RSC 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/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/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"