📝 Apply writing-skills review: common mistakes, portable greps, richer triggers

Author: mormubis

.claude/skills/upgrade-browser-sdk-v5/SKILL.md

@@ -251,6 +251,14 @@ The `"console error:"` prefix is removed from log messages. Update queries using
 
 Runtime errors, network logs, report logs, and console logs no longer inherit the main logger's context, level, or handler. Use global context and dedicated init parameters instead.
 
+## Common Mistakes
+
+| Mistake                                                                                      | What goes wrong                                                                                                             | Fix                                                                                                      |
+| -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| Setting `sessionReplaySampleRate > 0` without enabling `trackResources` and `trackLongTasks` | Resources and long tasks are silently not collected — they no longer default to `true` when using `sessionReplaySampleRate` | Always add `trackResources: true, trackLongTasks: true` alongside any non-zero `sessionReplaySampleRate` |
+| Using `context.event` instead of `context.events` in `beforeSend` for action events          | Action context property renamed — `context.event` is `undefined`, DOM event details are lost                                | Update to `context.events` (array); iterate if you need all associated DOM events                        |
+| Not updating CSP `connect-src` to the new v5 intake domains                                  | SDK silently fails to send data — old intake domains are no longer valid                                                    | Update `connect-src` to the v5 intake domain for your site (see Step 7)                                  |
+
 ## Verification checklist
 
 After upgrading, confirm:

.claude/skills/upgrade-browser-sdk-v6/SKILL.md

@@ -132,6 +132,14 @@ No code changes needed. The SDK dynamically loads an additional chunk when recor
 - **CSP**: Allow the dynamically loaded Session Replay chunk (e.g., `recorder-*-datadog-rum.js`) in `script-src` rules.
 - **Bundler config**: Ensure your bundler supports dynamic imports for Session Replay lazy loading.
 
+## Common Mistakes
+
+| Mistake                                                                           | What goes wrong                                                                                           | Fix                                                                                                                |
+| --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| Defensively disabling `trackUserInteractions`, `trackResources`, `trackLongTasks` | Disables features the project needs — these now default to `true`, which is usually the desired behavior  | Only set these to `false` if the project explicitly did not want them; leave them unset to accept the new defaults |
+| Missing `tracestate` in `Access-Control-Allow-Headers`                            | The `tracecontext` propagator now sends a `tracestate` header — cross-origin requests are blocked by CORS | Add `tracestate` alongside `traceparent` in your server's `Access-Control-Allow-Headers`                           |
+| Not updating CSP `script-src` for the lazy-loaded Session Replay chunk            | Recording silently fails on CSP-restricted pages — the dynamic chunk is blocked                           | Allow `recorder-*-datadog-rum.js` in `script-src`                                                                  |
+
 ## Verification checklist
 
 After upgrading, confirm:

.claude/skills/upgrade-browser-sdk-v7/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: upgrade-browser-sdk-v7
-description: Use when upgrading Datadog Browser SDK from v6 to v7, when encountering removed options like betaEncodeCookieOptions, allowFallbackToLocalStorage, trackBfcacheViews, usePciIntake, or when a project references datadoghq-browser-agent.com CDN with /v6/ paths
+description: Use when upgrading Datadog Browser SDK from v6 to v7, when encountering removed options like betaEncodeCookieOptions, allowFallbackToLocalStorage, trackBfcacheViews, usePciIntake, changed APIs like forwardErrorsToLogs, startDurationVital, stopDurationVital, or when a project references datadoghq-browser-agent.com CDN with /v6/ paths
 ---
 
 # Upgrade Datadog Browser SDK to v7
@@ -138,7 +138,7 @@ grep -rn 'startDurationVital\|stopDurationVital\|DurationVitalReference' \
 **Step 2 — find every variable that captures the return value** (this is the failure point):
 
 ```
-grep -rn '\(var\|const\|let\)\s\+\w\+\s*=\s*.*startDurationVital\|\w\+\s*=\s*DD_RUM\.startDurationVital\|\w\+\s*=\s*datadogRum\.startDurationVital' \
+grep -rEn '(var|const|let)\s+\w+\s*=\s*.+startDurationVital|\w+\s*=\s*DD_RUM\.startDurationVital|\w+\s*=\s*datadogRum\.startDurationVital' \
   --include="*.js" --include="*.ts" --include="*.tsx" --include="*.html"
 ```
 
@@ -150,7 +150,7 @@ For every match: remove the variable assignment and update all uses of that vari
 2. Find callers that capture the wrapper return value:
 
 ```
-grep -rn '\(var\|const\|let\)\s\+\w\+\s*=\s*.*[Ss]tart[Tt]iming\|\(var\|const\|let\)\s\+\w\+\s*=\s*.*[Ss]tart.*[Vv]ital' \
+grep -rEn '(var|const|let)\s+\w+\s*=\s*.+[Ss]tart[Tt]iming|(var|const|let)\s+\w+\s*=\s*.+[Ss]tart.+[Vv]ital' \
   --include="*.js" --include="*.ts" --include="*.tsx" --include="*.svelte" --include="*.vue"
 ```
 
@@ -201,6 +201,15 @@ These are **default changes** — no code breaks, but behavior differs from v6:
 - **CORS** (if using `allowedTracingUrls`): Add `"baggage"` to `Access-Control-Allow-Headers` on traced origins — or set `propagateTraceBaggage: false`.
 - **Browser support**: Minimum Chrome 80+, Firefox 78+, Safari 14+ (ES2020). ~0.048% less coverage.
 
+## Common Mistakes
+
+| Mistake                                                                    | What goes wrong                                                                                                     | Fix                                                                                                                                                |
+| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Replacing `forwardErrorsToLogs: true` with `forwardConsoleLogs: ['error']` | Unhandled errors (uncaught exceptions, unhandled rejections) stop being forwarded to Logs                           | Keep `forwardErrorsToLogs: true` unchanged and add `forwardConsoleLogs: ['error']` alongside it — they control different things                    |
+| Updating `startDurationVital` wrapper but not its callers                  | Callers pass the old ref variable (now `undefined`) to `stopDurationVital` — vital never stops, event never emitted | After updating the wrapper, search for every caller that captures the return value and update the stop call to pass the vital name string directly |
+| Missing `vitalKey` option on `stopDurationVital`                           | v7 `stopDurationVital` requires `{ vitalKey: string }` to identify which vital to stop                              | Pass the same string used in `startDurationVital`: `stopDurationVital('name', { vitalKey: 'name' })`                                               |
+| Not checking CDN/plain JS files for ref-based vitals                       | TypeScript projects surface this as a type error; plain JS silently breaks                                          | Run the Step 2 grep explicitly — don't rely on type errors to find all sites                                                                       |
+
 ## Verification checklist
 
 After upgrading, confirm:
@@ -212,3 +221,4 @@ After upgrading, confirm:
 - [ ] Distributed tracing working (no CORS errors from baggage header)
 - [ ] No `_dd_s` cookie remaining after first page load (should be `_dd_s_v2`)
 - [ ] Action names acceptable under new privacy defaults
+- [ ] No variables capturing the return value of `startDurationVital` (or wrappers around it) — all stop calls use the vital name string directly