docs(performance): recommend the Release Profiler → AI-agent .cpuprofile workflow (#40)

## What

Follow-up to the merged `mobile-performance` skill (#19). Adds a
recommended, validated workflow for root-causing a slow flow on a real /
RC build using the **React Native Release Profiler**, with the resulting
`.cpuprofile` analyzed either visually **or** by an AI coding agent.

### `references/mm-tools.md`

- Rewrote the **Release Profiler** section as clear numbered steps: grab
an RC build → shake → Performance Profiler → Start → run the flow → Stop
→ the `.cpuprofile` saves to Downloads → **analyze two ways:**
- **Visualize the flame graph:** `yarn react-native-release-profiler
--local <file.cpuprofile> [--sourcemap-path <maps>]` → SpeedScope /
`chrome://tracing` / Perfetto.
- **Or let AI read it:** hand the `.cpuprofile` to **Claude Code / your
AI agent of choice** and ask "why is this slow?" — it parses the
sampling profile and names the hot frames, no manual flame-graph
reading.
- Added an **"On an RC build"** decision-tree entry (RC tester / QA / a
flow that's only slow in release) so the profiler isn't gated to
production alerts only.

### `SKILL.md`

- Added a trigger for *analyzing a captured `.cpuprofile` / React Native
Release Profiler trace*, so handing over a profile fires this skill.

Uses `yarn` throughout (no `npx`), consistent with the repo conventions
and the rest of the skill.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: andrepimenta

domains/performance/skills/performance/references/mm-tools.md

@@ -110,8 +110,12 @@ Then read what's emitted — a load log (e.g. `source: 'cache' | 'fresh_fetch'`,
 "Prevent regressions going forward"
   → Reassure perf-test in CI  +  E2E performance gates (mms-performance-testing skill)
 
+"On an RC build" (RC tester, QA, or a flow that's only slow in release)
+  → React Native Release Profiler: shake → profile the flow → hand the .cpuprofile to
+    Claude Code / AI agent of choice to find the hot frames
+
 "Production alert / user report"
-  → Sentry (#metamask-mobile-release-monitoring) → Release Profiler on an RC build
+  → Sentry (#metamask-mobile-release-monitoring) → Release Profiler on an RC build (as above)
 
 "No tool isolates it"
   → Manual binary search (below)
@@ -182,7 +186,16 @@ EXPO_ATLAS=1 yarn expo export --platform ios && yarn expo-atlas
 - Dashboards + `#metamask-mobile-release-monitoring` alerts. `trace()` spans/measurements already flow here. Correlate regressions with release tags.
 
 ### React Native Release Profiler (production-like CPU profile)
-- RC build (TestFlight/Bitrise) → shake → Profiler → Start → reproduce → Stop → `yarn react-native-release-profiler --local <file.cpuprofile> [--sourcemap-path <maps>]` → open in `chrome://tracing` / SpeedScope / Perfetto. See `docs/readme/release-build-profiler.md`.
+Best way to root-cause a slow flow on a real build — and the lowest-effort to read:
+
+1. Grab an **RC build** — a release build; dev builds aren't representative.
+2. **Shake** the device → the **Performance Profiler** menu appears.
+3. **Start** the profiler, run the slow flow, then **Stop**. The `.cpuprofile` (a `sampling-profiler-trace*.cpuprofile`) saves to **Downloads**.
+4. **Analyze it — two ways:**
+   - **Visualize the flame graph:** symbolicate with `yarn react-native-release-profiler --local <file.cpuprofile> [--sourcemap-path <maps>]`, then open it in **SpeedScope** (speedscope.app) / `chrome://tracing` / Perfetto.
+   - **Or let AI read it:** hand the `.cpuprofile` to **Claude Code / your AI agent of choice** and ask "why is this slow?" — it parses the sampling profile and names the hot frames / culprit function for you, no flame-graph reading.
+
+See `docs/readme/release-build-profiler.md`.
 
 ### Manual binary search (last resort)
 1. Android device, go to the slow screen.

domains/performance/skills/performance/skill.md

@@ -1,4 +1,4 @@
 ---
 name: performance
-description: Use for any performance question about the MetaMask Mobile React Native app, at any stage. Trigger when: a screen, list, or interaction feels slow, laggy, or janky (account/network switching, scrolling, typing, FPS drops); planning a feature with real-time/websocket data, frequent updates, or large lists and wanting to avoid perf pitfalls before building; reviewing or auditing PRs/code for excessive re-renders, broken selector memoization, Context providers, hook deps, or bundle bloat; making the app faster for power users with many accounts/assets; measuring time-to-interactive, render counts, or FPS and surfacing them in Sentry; or adding render-regression tests so CI catches slowdowns. Covers re-renders, reselect memoization, FlashList, Reanimated, TTI, bundle size, and trace() instrumentation. Not for correctness bugs, styling/spacing, Solidity gas, or the browser extension.
+description: Use for any performance question about the MetaMask Mobile React Native app, at any stage. Trigger when: a screen, list, or interaction feels slow, laggy, or janky (account/network switching, scrolling, typing, FPS drops); planning a feature with real-time/websocket data, frequent updates, or large lists and wanting to avoid perf pitfalls before building; reviewing or auditing PRs/code for excessive re-renders, broken selector memoization, Context providers, hook deps, or bundle bloat; making the app faster for power users with many accounts/assets; measuring time-to-interactive, render counts, or FPS and surfacing them in Sentry; analyzing a captured `.cpuprofile` / React Native Release Profiler trace (e.g. a `sampling-profiler-trace*.cpuprofile`) to find why a flow is slow; or adding render-regression tests so CI catches slowdowns. Covers re-renders, reselect memoization, FlashList, Reanimated, TTI, bundle size, trace() instrumentation, and Release Profiler CPU-profile analysis. Not for correctness bugs, styling/spacing, Solidity gas, or the browser extension.
 ---