@kensaurus/skills 0.0.0-stage → 2.0.0

package/skills/audit-payment-system/references/checklist.md

@@ -0,0 +1,283 @@
+# Payment system audit — detection commands & signals
+
+Per-control detection for `audit-payment-system` Phase 2. Each entry: **what**, **detect** (commands),
+**good signal**, **red flag**, **fix via**. Amounts are always integer **minor units** (cents) as
+strings across boundaries — never floats. Run only the groups in scope for the detected tier (P0/P1/P2).
+
+---
+
+## A. Money-movement correctness
+
+### A1 — Idempotency on every mutation
+- **What:** charge/capture/refund/void accept a business-intent idempotency key, enforced at the API
+  edge **and** by a DB **unique constraint** (the last line of defense against a double charge).
+- **Detect:**
+  ```bash
+  rg -n -i "idempotency[-_]?key|Idempotency-Key|idempotenc" -g '*.{ts,js,py,go,java,rb,cs}'
+  rg -n -i "unique|UNIQUE|createIndex.*unique|@@unique|add_index.*unique" -g '*.{sql,prisma,rb,ts}' | rg -i "idempot|payment|charge|event"
+  rg -n -i "\.(create|charge|capture|refund|cancel|void)\b" -g '*.{ts,js,py,go}'   # do these calls pass a key?
+  ```
+- **Good:** every mutating call passes a key derived from business identity (order id + action), and a
+  `UNIQUE(idempotency_key)` (or `UNIQUE(order_id, action)`) exists in the schema.
+- **Red flag:** key generated from a timestamp/UUID at call time (defeats dedup on retry); key only at
+  the app layer with no DB constraint; some mutations keyed and others not.
+- **Fix via:** `audit-resilience`, `backend-patterns`.
+
+### A2 — Dedup / stored result & payload guard
+- **What:** a reused key returns the *prior* result (or a "processing" status); a reused key with a
+  **different** payload is rejected, not silently run.
+- **Detect:** `rg -n -i "already.?processed|existing.?result|payload.?hash|conflict|409" -g '*.{ts,js,py,go}'`
+- **Good:** persist the key + payload hash + response before calling the PSP; on reuse compare hash and
+  return the cached response.
+- **Red flag:** key accepted but result not stored; different payloads accepted under the same key.
+- **Fix via:** `audit-resilience`.
+
+### A3 — Payment state machine
+- **What:** explicit permitted/prohibited transitions; `capture` twice is idempotent (2nd call returns
+  success without re-processing); no `SETTLED→AUTHORIZED`, no re-capture of `REFUNDED`.
+- **Detect:**
+  ```bash
+  rg -n -i "state|status|transition|PENDING|AUTHORIZED|CAPTURED|SETTLED|REFUNDED|FAILED|CHECK constraint" -g '*.{ts,js,py,go,sql}'
+  ```
+- **Good:** a defined transition graph (enum + guard, DB `CHECK`, or state-machine lib); capture/refund
+  are guarded and idempotent; a background worker resolves stuck transitional states (see C5).
+- **Red flag:** free-form status string set anywhere; capture with no "already captured" guard; no
+  prohibited-transition checks.
+- **Fix via:** `backend-patterns`.
+
+### A4 — Money as integer minor units
+- **What:** amounts are integers (cents), currency carried alongside; no float arithmetic on money.
+- **Detect:** `rg -n -i "float|double|parseFloat|Number\(|decimal|BigDecimal|toFixed|amount\s*[*/]" -g '*.{ts,js,py,go,java,sql}'`
+- **Good:** `amount_minor int` / `bigint` + `currency char(3)`; money math in integer or a decimal type;
+  amounts crossing boundaries as strings in minor units.
+- **Red flag:** `float`/`double`/`parseFloat` on money; `toFixed(2)` as the storage strategy; summing
+  across currencies.
+- **Fix via:** `audit-db-schema`.
+
+### A5 — Multi-currency & FX
+- **What:** no cross-currency arithmetic; FX rate captured at posting time and stored with the entry;
+  explicit rounding policy (e.g. bankers'/half-even).
+- **Detect:** `rg -n -i "currency|fx|exchange.?rate|convert|round|banker" -g '*.{ts,js,py,go,sql}'`
+- **Good:** each ledger entry stores currency + fx rate used; conversions produce a recorded FX entry;
+  documented rounding.
+- **Red flag:** adding amounts of different currencies; FX rate re-fetched at read time; unspecified
+  rounding.
+- **Fix via:** `backend-patterns`.
+
+---
+
+## B. Ledger & data integrity  *(P1 internal balances · P2 full ledger — `N/A` for P0)*
+
+### B1 — Double-entry
+- **What:** every movement writes a balanced debit **and** credit; the sum of all ledger entries = 0.
+- **Detect:** `rg -n -i "debit|credit|double|balanced|journal|posting|sum.*zero" -g '*.{ts,js,py,go,sql}'`
+- **Good:** a `ledger_entries` table with `direction (debit|credit)`, entries grouped by a
+  transaction/journal id, and an invariant/test asserting per-transaction debits == credits.
+- **Red flag:** a single "amount +/-" column; balances mutated directly without paired entries.
+- **Fix via:** `audit-db-schema`, `backend-patterns`.
+
+### B2 — Append-only / immutable
+- **What:** transaction & ledger tables are insert-only; corrections are **reversing entries**, never
+  `UPDATE`/`DELETE`.
+- **Detect:**
+  ```bash
+  rg -n -i "UPDATE (ledger|transactions|journal|entries)|DELETE FROM (ledger|transactions|journal)" -g '*.{sql,ts,js,py,go,rb}'
+  rg -n -i "\.update\(|\.destroy\(|\.delete\(" -g '*.{ts,js,py,go,rb}' | rg -i "ledger|transaction|journal|entry"
+  ```
+- **Good:** no update/delete on financial tables; DB trigger/grant prevents it; reversals are new rows.
+- **Red flag:** any `UPDATE`/`DELETE` against ledger/transaction rows.
+- **Fix via:** `plan-data-integrity`, `audit-db-schema`.
+
+### B3 — Balance derived & snapshotted separately
+- **What:** current balance is a materialized snapshot of ledger entries, not a hand-updated column.
+- **Detect:** `rg -n -i "balance|snapshot|materialized|SUM\(|running.?total" -g '*.{ts,js,py,go,sql}'`
+- **Good:** balance = periodic snapshot + entries since; snapshot table separate from ledger.
+- **Red flag:** `balance = balance + x` UPDATE alongside (or instead of) ledger entries.
+- **Fix via:** `audit-db-schema`.
+
+### B4 — Auditability
+- **What:** immutable/event-sourced history reconstructs any transaction; access to txn/PII data logged.
+- **Detect:** `rg -n -i "audit|event.?source|history|append|access.?log|who|actor" -g '*.{ts,js,py,go,sql}'`
+- **Good:** every state change emits an immutable event; reads/writes of payment data are attributable.
+- **Red flag:** no history table; no access logging on payment/PII reads.
+- **Fix via:** `backend-observability`, `audit-security`.
+
+### B5 — Schema for scale
+- **What:** time-partitioned transaction/ledger tables (manageable rows/day); indexes for recon queries.
+- **Detect:** `rg -n -i "PARTITION|partition by|created_at.*index|BRIN|shard" -g '*.{sql,prisma}'`
+- **Good:** partition by date; indexes on `(created_at)`, `(idempotency_key)`, `(status)`.
+- **Red flag:** one unbounded hot table; recon full-scans.
+- **Fix via:** `audit-db-schema`.
+
+---
+
+## C. Async orchestration & webhook delivery
+
+### C1 — Sync-auth vs async-everything
+- **What:** authorization is synchronous (caller waits); settlement, webhooks, reporting, recon are async.
+- **Detect:** `rg -n -i "await.*capture|await.*settle|await.*reconcil|await.*notify|await.*email" -g '*.{ts,js,py,go}'`
+- **Good:** only auth/confirm is on the request path; the rest is queued.
+- **Red flag:** blocking on settlement/reporting/email inside the checkout request.
+- **Fix via:** `audit-backend-architecture`.
+
+### C2 — Webhook signature verified before processing
+- **What:** HMAC / provider `constructEvent` verification happens **before** any state change.
+- **Detect:**
+  ```bash
+  rg -n -i "constructEvent|verifyHeader|Stripe-Signature|hmac|createHmac|timingSafeEqual|verify.*signature|x-.*-signature" -g '*.{ts,js,py,go,rb}'
+  rg -n -i "app\.(post|put)\(.*webhook|@app.route.*webhook|/webhook" -g '*.{ts,js,py,go,rb}'   # then check each verifies
+  ```
+- **Good:** every webhook route verifies the signature with the raw body and a constant-time compare.
+- **Red flag:** webhook handler parses/acts on the body with no verification; signature compared with `==`.
+- **Fix via:** `audit-security`.
+
+### C3 — Event-id dedup + 200-then-process
+- **What:** processed event ids are recorded; the endpoint acks **200 immediately** then processes async.
+- **Detect:** `rg -n -i "event\.id|processed.?event|already.?seen|enqueue|queue|200|res\.(send|status)" -g '*.{ts,js,py,go}'`
+- **Good:** insert event id into a `processed_events` table (unique); return 200 fast; process on a worker.
+- **Red flag:** synchronous heavy processing inside the webhook (PSP retries on timeout → double process);
+  no event-id dedup.
+- **Fix via:** `audit-resilience`.
+
+### C4 — Atomic state + ledger + outbox
+- **What:** the state transition, ledger posting, and outbound event are committed in **one** DB
+  transaction; a relay publishes from the outbox.
+- **Detect:** `rg -n -i "transaction|BEGIN|commit|outbox|\.\$transaction|unit.?of.?work" -g '*.{ts,js,py,go,sql}'`
+- **Good:** single DB txn wraps state+ledger+outbox insert; separate relay/CDC publishes events.
+- **Red flag:** DB write then a separate `publish()`/HTTP call (dual-write — crash between = inconsistency).
+- **Fix via:** `audit-backend-architecture`, `backend-patterns`.
+
+### C5 — Pull-based recovery for stuck payments
+- **What:** a worker scans transitional states past a timeout and queries the PSP as the source of truth.
+- **Detect:** `rg -n -i "cron|scheduler|worker|poll|stuck|reconcile.*status|retrieve.*payment|pull" -g '*.{ts,js,py,go}'`
+- **Good:** periodic sweep of `PENDING`/`PROCESSING` older than N minutes → PSP status API drives the transition.
+- **Red flag:** state advanced **only** by inbound webhooks (a lost webhook = stuck forever → user retries → double charge).
+- **Fix via:** `backend-patterns`.
+
+### C6 — Refund/dispute/payout as saga
+- **What:** multi-service flows use local steps + **compensations** (reverse auth, negative ledger entry,
+  payout clawback, notify), driven by a durable workflow.
+- **Detect:** `rg -n -i "saga|compensat|workflow|temporal|step.?function|rollback|clawback" -g '*.{ts,js,py,go}'`
+- **Good:** each step has a compensating action; a durable engine won't lose an in-flight saga on crash.
+- **Red flag:** a refund that reverses money but can fail before notifying/booking, with no compensation.
+- **Fix via:** `backend-patterns`.
+
+---
+
+## D. Reconciliation & settlement  *(P1/P2 — `N/A` for P0 beyond PSP-dashboard spot checks)*
+
+### D1 — Automated daily reconciliation
+- **Detect:** `rg -n -i "reconcil|settlement|balance_transaction|payout.?report|settle.*file|EOD|end.?of.?day" -g '*.{ts,js,py,go}'`
+- **Good:** a scheduled job ingests the PSP settlement file and matches every line to a ledger entry.
+- **Red flag:** no reconciliation job at all (ledger and PSP diverge silently).
+- **Fix via:** `backend-patterns`, `data-pipeline`.
+
+### D2 — 3-way match + break report
+- **What:** internal ledger ↔ card-network/PSP ↔ bank statement; output a break report for ops.
+- **Detect:** `rg -n -i "three.?way|3.?way|match|discrepanc|break.?report|mismatch|unmatched" -g '*.{ts,js,py,go}'`
+- **Good:** all three sources compared; matched/unmatched/mismatched categorized daily.
+- **Red flag:** only ledger-vs-PSP (bank ignored); no break report.
+- **Fix via:** `data-pipeline`.
+
+### D3 — Discrepancy handling
+- **What:** missing txn escalated; extra bank txn found-in-records or reversed; amount mismatch checks FX;
+  rounding-only differences auto-resolved.
+- **Detect:** `rg -n -i "escalat|alert|missing|extra|amount.?mismatch|fx|rounding|auto.?resolve" -g '*.{ts,js,py,go}'`
+- **Good:** typed discrepancy handlers with thresholds; rounding auto-resolved, real breaks escalated.
+- **Red flag:** breaks logged and ignored, or every break requires manual triage.
+- **Fix via:** `backend-patterns`.
+
+### D4 — Safety brake
+- **What:** unreconciled balance over a threshold halts new captures / pages on-call.
+- **Detect:** `rg -n -i "halt|threshold|circuit|stop.*capture|alert|pager|page" -g '*.{ts,js,py,go}'`
+- **Red flag:** losses can accumulate indefinitely with no automated stop.
+- **Fix via:** `audit-resilience`.
+
+---
+
+## E. Fraud, risk & SCA
+
+### E1 — Risk scoring pre-auth
+- **Detect:** `rg -n -i "fraud|risk|velocity|geolocat|device.?fingerprint|rules?.?engine|ml|score|radar|sift" -g '*.{ts,js,py,go}'`
+- **Good:** velocity/geo/amount/device signals feed a rules engine (+ ML score if present) before auth.
+- **Red flag:** no pre-auth screening (card-testing/stolen-card attacks land as chargebacks).
+- **Fix via:** `backend-patterns` (P0: delegate to the PSP's built-in, e.g. Stripe Radar).
+
+### E2 — 3DS2 / SCA step-up
+- **Detect:** `rg -n -i "3ds|3-?d.?secure|sca|strong.?customer|psd2|challenge|exempt|frictionless" -g '*.{ts,js,py,go}'`
+- **Good:** high-risk / PSD2-region → 3DS challenge; low-risk → frictionless via exemptions; PaymentIntents
+  (which handles SCA) not the legacy Charges API.
+- **Red flag:** no SCA for EU cards (declines); or challenge on everything (lost conversion).
+- **Fix via:** provider docs / `backend-patterns`.
+
+### E3 — Fraud-service failure policy
+- **Detect:** `rg -n -i "fail.?open|fail.?closed|fallback|circuit|degrade|timeout" -g '*.{ts,js,py,go}' | rg -i "fraud|risk"`
+- **Good:** an explicit, documented fail-open **or** fail-closed decision behind a breaker.
+- **Red flag:** undefined behavior when the risk service is down (blocks all revenue, or waves all fraud through).
+- **Fix via:** `audit-resilience`.
+
+### E4 — Chargeback / dispute monitoring
+- **Detect:** `rg -n -i "chargeback|dispute|VAMP|VDMP|ratio|watchlist" -g '*.{ts,js,py,go}'`
+- **Good:** dispute ratio tracked with alerting well below acquirer thresholds.
+- **Red flag:** no visibility into dispute rate.
+- **Fix via:** `backend-observability`.
+
+### E5 — AML / sanctions  *(P2 / regulated)*
+- **Detect:** `rg -n -i "aml|kyc|sanction|ofac|watchlist|screening" -g '*.{ts,js,py,go}'`
+- **Fix via:** `/research` + human review (regulatory).
+
+---
+
+## F. Compliance & security — PCI DSS v4.0.1 (all tiers)
+
+### F1 — Never store/log PAN or CVV
+- **Detect (should find nothing raw):**
+  ```bash
+  rg -n -i "card[-_ ]?number|\bpan\b|cvv|cvc|card\.number|primary_account|expiry|exp_month|exp_year" -g '*.{ts,js,py,go,java,rb,cs,sql,log}'
+  rg -n -i "console\.log|logger\.(info|debug)|print\(|fmt\.Print" -g '*.{ts,js,py,go}' | rg -i "card|pan|cvv|token|amount|payment"
+  ```
+- **Good:** raw card data never reaches your servers (hosted fields / Elements); only tokens stored/logged.
+- **Red flag (Critical):** any PAN/CVV in code, DB columns, or logs. CVV storage is flatly prohibited.
+- **Fix via:** `audit-security`.
+
+### F2 — Tokenization
+- **Detect:** `rg -n -i "token|payment_method|setup_intent|hosted.?field|elements|vault" -g '*.{ts,js,py,go}'`
+- **Good:** PaymentIntents / hosted fields keep card data out of scope (SAQ-A).
+- **Red flag:** card data posted to your backend then forwarded (full PCI scope).
+- **Fix via:** provider docs.
+
+### F3 — Key rotation & secret handling
+- **Detect:** `rg -n -i "sk_live|sk_test|api.?key|secret|whsec_|signing.?secret|rotate" -g '*.{ts,js,py,go,env,yml,yaml}'`
+- **Good:** keys in a secret manager, rotated; webhook signing secret not in code.
+- **Red flag (Critical):** live secret keys committed; no rotation.
+- **Fix via:** `audit-security`, `plan-secrets-audit`.
+
+### F4 — Access audit
+- **Detect:** `rg -n -i "audit.?log|access.?log|who|actor|user_id.*read|trace" -g '*.{ts,js,py,go}' | rg -i "payment|transaction|card|ledger"`
+- **Good:** every read/write of payment/PII data is attributable.
+- **Red flag:** no access trail on payment data.
+- **Fix via:** `audit-security`, `backend-observability`.
+
+---
+
+## G. Error handling & resilience
+
+- **G1 timeout + backoff + breaker on PSP/bank calls:** `rg -n -i "timeout|retry|backoff|jitter|circuit|breaker|opossum|resilience4j|polly|tenacity" -g '*.{ts,js,py,go}'` → every external call has a timeout and a breaker. Red flag: bare `await fetch(psp)` with no timeout. Fix via `audit-resilience`.
+- **G2 bulkhead / pool isolation:** `rg -n -i "pool|semaphore|bulkhead|max.?concurren|limit" -g '*.{ts,js,py,go}'` → PSP calls can't starve the DB pool. Fix via `audit-backend-architecture`.
+- **G3 partial-write safety:** covered by C4 (state + ledger commit atomically). Red flag: "charged but not booked" possible. Fix via `backend-patterns`.
+- **G4 graceful degradation:** `rg -n -i "degrade|fallback|optional|non.?critical|best.?effort" -g '*.{ts,js,py,go}'` → fraud/notification down ≠ block auth, per an explicit policy. Fix via `audit-resilience`.
+
+---
+
+## Delegation map (don't double-count)
+| Concern | Owner skill |
+|---|---|
+| Per-call timeout/retry/backoff/breaker/idempotency-key mechanics | `audit-resilience` |
+| PAN/CVV handling, webhook auth, secrets, key rotation, access logging, injection | `audit-security` |
+| Ledger schema, money types, append-only constraints, partitioning | `audit-db-schema` |
+| Outbox/saga/breaker *structure* & topology fit | `audit-backend-architecture` |
+| Append-only/immutability & destructive-op safety | `plan-data-integrity` |
+| Rotate-vs-relocate provider keys | `plan-secrets-audit` |
+| Implementation of idempotency/outbox/saga/state machine | `backend-patterns` |
+| Reconciliation/settlement ingestion pipelines | `data-pipeline` |
+| Stripe-specific integration detail | Stripe plugin skills + Stripe MCP |

package/skills/audit-performance/SKILL.md

@@ -0,0 +1,383 @@
+---
+name: audit-performance
+description: >
+  Audit and fix runtime performance (Core Web Vitals, load priority). Use when
+  "slow page", "LCP/INP/CLS", "fetchpriority", "long tasks", or "bfcache". JS
+  payload → audit-bundle-size. Instant nav → enhance-web-instant-nav. Load
+  limits → test-load.
+license: MIT
+effort: high
+---
+
+# Performance Audit Skill
+
+**Degree of freedom: MIXED** — what to optimize `[HIGH freedom]`;
+measure-first Sentry/vitals and `EXPLAIN` `[LOW freedom — run exactly]`.
+
+> **Audit-and-fix exception.** Measure, then optimize. JS payload → `audit-bundle-size`. Instant navigations → `enhance-web-instant-nav`. Breaking point → `test-load`. Timeouts/retries → `audit-resilience`.
+> When fixing: change only the measured bottleneck and re-measure it; log other slow paths you notice as follow-ups, not fixes. Edit the existing file in place rather than rewriting it. Add a perf test only where the repo already keeps them or the task asks; scratch measurements stay out of the repo.
+
+## How to reason
+
+1. **Observe** — quote LCP/INP/CLS, p95, or `EXPLAIN` / N+1 loop (`file:line`)
+2. **Interpret** — is the user waiting on bytes, a query, or main-thread work?
+3. **Classify** — vital-miss / N+1 / missing-index / bundle / image / re-render
+4. **Severity** — poor LCP/INP or p95 >> target on a live path = Critical
+
+## Worked example
+
+> **Observe:** Sentry p95 `/users` = 2.3s; handler `findAll` then per-user
+> `Order.findByUserId` (`app/api/users/route.ts:31`).
+> **Interpret:** N+1; TTFB/LCP suffer on that page.
+> **Classify:** N+1.
+> **Severity:** Critical (p95 far over 200ms).
+> **Finding:** `/users` | N+1 | eager-load orders | then re-measure
+
+## Step 0: Gather Performance Data  [LOW freedom — run exactly]
+
+Before optimizing, measure. Collect data from multiple sources.
+
+### Production Data (Sentry)
+
+If Sentry performance monitoring is enabled, fetch real production metrics:
+
+```json
+sentry:search_events
+{
+ "organizationSlug": "<ORG_SLUG>",
+ "projectSlug": "<PROJECT_SLUG>",
+ "regionUrl": "<REGION_URL>",
+ "query": "slowest transactions by p95 duration in last 7 days",
+ "limit": 20
+}
+```
+
+```json
+sentry:search_events
+{
+ "organizationSlug": "<ORG_SLUG>",
+ "projectSlug": "<PROJECT_SLUG>",
+ "regionUrl": "<REGION_URL>",
+ "query": "web vitals LCP INP CLS performance scores in last 7 days",
+ "limit": 20
+}
+```
+
+Check for performance-related issues:
+
+```json
+sentry:search_issues
+{
+ "organizationSlug": "<ORG_SLUG>",
+ "projectSlugOrId": "<PROJECT_SLUG>",
+ "regionUrl": "<REGION_URL>",
+ "query": "performance issues slow queries N+1 in last 30 days",
+ "limit": 20
+}
+```
+
+### Research Current Benchmarks
+
+Fetch current performance targets:
+
+```json
+firecrawl:firecrawl_search
+{
+ "query": "web vitals thresholds good score <current year>",
+ "limit": 3,
+ "sources": [{ "type": "web" }]
+}
+```
+
+### Field Data (source of truth)  [LOW freedom — run exactly]
+
+Lab (Lighthouse) is for diagnosis; **field** decides pass/fail.
+
+1. CrUX / PageSpeed Insights field tab for the origin and top 5 URLs by
+   traffic — record p75 LCP / INP / CLS (mobile first).
+2. `web-vitals/attribution` in the app (not the base build): it names the
+   LCP element, the INP interaction target, and the CLS-shifting node.
+3. Lighthouse CI with a `budget.json` (see `references/loading-priority-2026.md`
+   §Budgets). Fail the PR on regression, not on absolute score.
+
+Record all three in the report's "Production Metrics" block before touching code.
+
+### Verification protocol  [LOW freedom — run exactly]
+
+```bash
+# Field (source of truth): CrUX / PSI field tab → p75 LCP, INP, CLS
+# Lab, repeatable, budgeted:
+npx @lhci/cli autorun --config=lighthouserc.json
+# Early Hints present?
+curl -sv https://example.com/ 2>&1 | grep -E "< HTTP/.* 103"
+# Speculation: DevTools → Application → Speculative loads
+# bfcache:     DevTools → Application → Back/forward cache → Test
+# LCP element: web-vitals/attribution → onLCP(({attribution}) => attribution.element)
+```
+
+---
+
+## Performance Targets
+
+### Core Web Vitals
+
+| Metric | Good | Needs Work | Poor |
+|--------|------|------------|------|
+| **LCP** (Largest Contentful Paint) | <2.5s | 2.5-4s | >4s |
+| **INP** (Interaction to Next Paint) | <200ms | 200-500ms | >500ms |
+| **CLS** (Cumulative Layout Shift) | <0.1 | 0.1-0.25 | >0.25 |
+
+### Other Key Metrics
+
+- **TTFB**: <800ms field p75 (Google threshold); aim <200ms at the edge
+- **FCP**: <1.8s
+- **Long tasks**: none >50ms on the critical interaction path (INP driver)
+- **LCP resource load delay**: <100ms (gap between TTFB and the LCP image request starting — usually "image not discoverable / not preloaded")
+- **bfcache**: eligible on every content page (DevTools → Application → Back/forward cache)
+
+---
+
+## Frontend Performance Audit  [HIGH freedom]
+
+### Bundle Size Analysis
+
+```bash
+npm run build -- --analyze # framework-specific
+npx source-map-explorer 'dist/**/*.js'
+```
+
+**Checklist:**
+- [ ] Total bundle <200KB gzipped
+- [ ] No single chunk >100KB gzipped
+- [ ] Tree shaking working (no unused exports in bundle)
+- [ ] Heavy libraries lazy-loaded (charts, editors, maps)
+- [ ] No moment.js (use date-fns or dayjs)
+- [ ] No lodash full import (use lodash-es or specific imports)
+
+### Code Splitting
+
+- [ ] Route-based splitting (each page loads its own chunk)
+- [ ] Component-level splitting for heavy components (`lazy()` / `dynamic()`)
+- [ ] Below-fold content deferred
+
+### Image Optimization
+
+- [ ] WebP/AVIF format used (not PNG/JPEG for photos)
+- [ ] Images sized appropriately (not serving 4K to mobile)
+- [ ] `loading="lazy"` on below-fold images
+- [ ] Responsive `srcSet` for different screen sizes
+- [ ] Image CDN used (Cloudinary, imgix, Vercel Image Optimization)
+
+### Loading Priority & Speculation  [HIGH freedom on which to apply, LOW freedom on the LCP rules]
+
+Deep syntax: `references/loading-priority-2026.md`. Instant-nav implementation → `enhance-web-instant-nav`.
+
+**LCP element (find it first with `web-vitals/attribution` or DevTools → Performance → LCP)**
+- [ ] LCP image is **not** `loading="lazy"` — lazy on the LCP image is an automatic Critical finding
+- [ ] LCP image has `fetchpriority="high"` (Next.js: `<Image priority />`, which also injects the preload)
+- [ ] LCP image is discoverable from HTML — not a CSS `background-image`, not injected by client JS, not behind a hydration boundary
+- [ ] `<link rel="preload" as="image" imagesrcset imagesizes>` when the LCP image is responsive and not already preloaded by the framework
+- [ ] Non-critical images: `loading="lazy" decoding="async"`; `<picture>` AVIF → WebP → JPEG fallback
+
+**Fonts**
+- [ ] `font-display: swap` (or `optional` for non-brand text); fallback metrics set (`size-adjust`, `ascent-override`) so swap causes no CLS — `next/font` does this automatically, verify it's actually used
+- [ ] Preload only the above-fold weight(s); subset to used unicode ranges; self-host
+
+**Early Hints (103)**
+- [ ] Origin/CDN sends `103 Early Hints` with `preconnect` for the image/font CDN and `preload` for the LCP image + critical CSS. Verify: `curl -sv https://site/ 2>&1 | grep -i "< HTTP/.* 103"`
+- [ ] Node: `res.writeEarlyHints({ link: [...] })`; otherwise configure at the CDN
+
+**Speculation Rules (next-navigation speed)**
+- [ ] `<script type="speculationrules">` present with `prefetch` document rules at `moderate` eagerness for in-site links
+- [ ] `prerender` only for high-probability next pages (pagination, "next article", product detail); eagerness `moderate`/`conservative`
+- [ ] Excluded from speculation: logout, cart/checkout, auth, anything with side effects on GET, URLs with `?` unless `expects_no_vary_search` is set
+- [ ] Server ignores side-effects when `Sec-Purpose: prefetch;prerender` is present; analytics/ads guarded by `document.prerendering` + `prerenderingchange`
+- [ ] Full implementation → `enhance-web-instant-nav`
+
+**bfcache**
+- [ ] No `unload` listeners (use `pagehide`); no `Cache-Control: no-store` on HTML; no open WebSocket / IndexedDB transaction at `pagehide`
+- [ ] Verified green in DevTools → Application → Back/forward cache → "Test back/forward cache"
+
+**Render strategy (Next.js 16 / React 19)**
+- [ ] Server Components by default; `'use client'` only at interactive leaves
+- [ ] Slow data wrapped in `<Suspense>` so the shell streams; static shell + dynamic holes (`cacheComponents` / `'use cache'`) instead of blocking the whole route
+- [ ] React Compiler enabled (`reactCompiler: true`) **before** any manual `memo`/`useMemo`/`useCallback` — manual memo only where Profiler proves the Compiler missed it
+
+**INP (responsiveness)**
+- [ ] No task >50ms on tap/click/keypress paths; break work with `scheduler.yield()` (fallback `setTimeout(0)`) or `startTransition`
+- [ ] No synchronous layout reads (`offsetHeight`, `getBoundingClientRect`) inside input handlers
+- [ ] `content-visibility: auto` + `contain-intrinsic-size` on long off-screen sections
+- [ ] Third-party scripts: `async`/`defer`, Next `<Script strategy="lazyOnload">` (or `"worker"` via Partytown where safe), consent-gated, facades for embeds (lite-youtube, static map image → iframe on click)
+
+**CLS**
+- [ ] Every `<img>`, `<video>`, `<iframe>`, ad slot has `width`/`height` or `aspect-ratio`
+- [ ] Late-arriving UI (banners, toasts, cookie bars) reserves space or overlays — never pushes content
+
+### React Performance (if applicable)
+
+- [ ] React Compiler on; manual memo only with Profiler evidence (see Loading Priority & Speculation)
+- [ ] No unnecessary re-renders (React DevTools Profiler)
+- [ ] Long lists virtualized (react-window, @tanstack/react-virtual)
+- [ ] No inline object/array creation in JSX props
+- [ ] Context providers scoped narrowly (not wrapping entire app for local state)
+
+### CSS Performance
+
+- [ ] No layout thrashing (reads before writes)
+- [ ] Animations use `transform`/`opacity` (GPU-accelerated)
+- [ ] No `@import` chains (bundled instead)
+- [ ] Critical CSS inlined for above-fold content
+- [ ] Fonts subset and preloaded (`<link rel="preload">`)
+
+---
+
+## Backend Performance Audit  [HIGH freedom]
+
+### Database Queries
+
+**N+1 Detection:**
+```typescript
+// BAD: N+1
+const users = await User.findAll();
+for (const user of users) {
+ const orders = await Order.findByUserId(user.id);
+}
+
+// GOOD: eager loading
+const users = await User.findAll({ include: [Order] });
+```
+
+**Checklist:**
+- [ ] N+1 queries eliminated (eager loading, joins, batch loading)
+- [ ] Indexes on frequently queried columns (WHERE, JOIN, ORDER BY)
+- [ ] SELECT only needed columns (no `SELECT *`)
+- [ ] Pagination on all list endpoints
+- [ ] Connection pooling configured
+- [ ] Slow query logging enabled
+
+**Index verification:**  [LOW freedom — run exactly]
+```sql
+EXPLAIN ANALYZE SELECT * FROM orders WHERE user_id = '123';
+```
+
+### API Response Optimization
+
+- [ ] Response compression enabled (gzip/brotli)
+- [ ] Appropriate cache headers (`Cache-Control`, `ETag`)
+- [ ] No over-fetching (return only what the client needs)
+- [ ] Pagination for list endpoints
+- [ ] Response time <200ms for p95
+
+### Caching Strategy
+
+| Layer | Tool | TTL | Use For |
+|-------|------|-----|---------|
+| Browser | Cache-Control headers | Varies | Static assets, API responses |
+| CDN | Vercel/CloudFront/Cloudflare | 1h-1d | Static pages, images |
+| API | Redis/Memcached | 5m-1h | Expensive queries, computed data |
+| ORM | Query cache | 1m-5m | Repeated identical queries |
+
+### Network Optimization
+
+- [ ] CDN for static assets
+- [ ] HTTP/2 or HTTP/3 enabled
+- [ ] Preconnect to critical origins (`<link rel="preconnect">`)
+- [ ] DNS prefetch for third-party domains
+- [ ] API calls batched where possible (GraphQL, DataLoader)
+
+---
+
+## Research-Driven Optimization  [HIGH freedom]
+
+For specific performance bottlenecks, research current solutions:
+
+```json
+firecrawl:firecrawl_search
+{
+ "query": "<framework> <specific bottleneck> performance optimization <current year>",
+ "limit": 5,
+ "sources": [{ "type": "web" }]
+}
+```
+
+Then deep-read the best result:
+
+```json
+firecrawl:firecrawl_scrape
+{
+ "url": "<best-result-url>",
+ "formats": ["markdown"],
+ "onlyMainContent": true
+}
+```
+
+Check official framework docs via Context7:
+
+```json
+context7:resolve-library-id
+{
+ "libraryName": "<framework>",
+ "query": "performance optimization"
+}
+```
+
+---
+
+## Quick Wins (Highest Impact, Lowest Effort)
+
+| Issue | Solution | Impact |
+|-------|----------|--------|
+| LCP image lazy / not prioritized | `fetchpriority="high"` + preload; remove `loading="lazy"` from LCP | High (−300 to −800 ms LCP) |
+| Fast first page, slow second | Speculation Rules `prefetch` (moderate) | High (next-nav TTFB ≈ 0) |
+| Manual memo everywhere | Enable React Compiler | High (INP; delete redundant memo) |
+| Large bundle | Code split routes, lazy load heavy libs | High |
+| Slow images | WebP + lazy load + responsive | High |
+| No caching | Add Cache-Control headers | High |
+| N+1 queries | Eager load / batch | High |
+| Missing indexes | Add database indexes | High |
+| Unoptimized fonts | Subset + preload + font-display:swap | Medium |
+| No compression | Enable gzip/brotli | Medium |
+| Expensive re-renders | React Compiler first; manual memo only with Profiler evidence | Medium |
+| Layout shifts | Set explicit width/height on images/embeds | Medium |
+
+---
+
+## Self-critique before applying fixes  [LOW freedom — do not skip]
+
+1. **Evidenced** — a measured vital, p95, or `EXPLAIN`, not "this looks slow"
+2. **Reproducible** — same path still exceeds the target table
+3. **Severity justified** — Critical = poor vital or live-path p95
+4. **Right owner** — JS payload → `audit-bundle-size`; breaking point → `test-load`; timeouts → `audit-resilience`
+5. **No-false-safety** — no `memo`/`useMemo` without a measured re-render; measure again after the fix
+6. **LCP named** — prove which element is LCP before recommending image fixes (no attribution data = guess, not audit)
+
+## Output: Performance Audit Report
+
+```markdown
+## Performance Audit: [Project Name]
+
+### Production Metrics (from Sentry)
+- LCP: [value] — [good/needs work/poor]
+- INP: [value] — [good/needs work/poor]
+- CLS: [value] — [good/needs work/poor]
+- Slowest transactions: [list with p95 times]
+
+### Critical Issues (fix immediately)
+| # | Area | Issue | Impact | Fix |
+|---|------|-------|--------|-----|
+| 1 | DB | N+1 on /users endpoint | p95 = 2.3s | Eager load orders relation |
+
+### Optimizations (prioritized)
+| # | Area | Issue | Impact | Effort | Fix |
+|---|------|-------|--------|--------|-----|
+| 1 | FE | Bundle 450KB gzipped | High | Low | Code split routes |
+
+### Already Optimized
+- [list of performance areas that are well-implemented]
+
+### Monitoring Recommendations
+- [what to add to track performance over time]
+
+### Research Sources
+- [URL] — [what optimization pattern it provided]
+```