/argent-react-native-profiler

name: argent-react-native-profiler
description: Profile a React Native Hermes app to measure re-render and CPU performance using argent profiler tools. Use when optimizing for performance, measuring before/after a fix, spotting slow components, diagnosing re-renders, checking CPU hotspots, or producing a ranked issue report.

This skill is complementary to `argent-react-native-optimization`, not a replacement for it.

Physical iPhone: not supported; `react-profiler-*` reject `kind: "device"`. Profile on a simulator.

1. Tools

React Profiler (Hermes / React commits)

• `react-profiler-start` / `react-profiler-stop`: record CPU samples and React commits around an interaction.
• `react-profiler-analyze`: turn the recording into a ranked report: hot commits with the JS functions that ran during each, and the file and line of each ranked component it finds in the project.
• `react-profiler-status`: **only after an interruption** (debugger drop, Metro reload, pause, subagent handoff, any doubt), never otherwise. After a debugger drop, react-profiler-stop can no longer collect the run; check status before stopping or restarting.
• `react-profiler-fiber-tree`: live component hierarchy, no session needed, for tracing a component's ancestry.

Drill-down queries (after analyze)

• `profiler-cpu-query`: JS CPU: top functions, a time window, a function's call tree, CPU during a component's commits.
• `profiler-commit-query`: React commits by component, time range, commit index, or cascade tree, and render counts over all commits.
• `profiler-stack-query`: native data: hang stacks, function callers, thread breakdown, leak details.
• `profiler-combined-report`: correlates native hangs with React commits when both profilers ran.
• `profiler-load`: reload an earlier session from disk for the query tools.

For native profiling on its own, see the `argent-native-profiler` skill.

2. Guidelines

• Start `react-profiler-start` and `native-profiler-start` together, as `react-profiler-start` describes. If the user wants only native profiling, follow `argent-native-profiler`.
• **Never move on silently after a report.** The report is the starting point: ask the user whether to investigate further with the query tools, implement fixes and re-profile, or stop.
• **Record the interaction as an e2e test** (`argent-create-e2e` skill) before the first run when profiling needs a specific interaction sequence (scroll a list, navigate screens, trigger an animation), then replay it for every later run. This removes interaction variance from before/after comparisons. It matters most when re-profiling after a fix, comparing several sessions, or when the path is more than 2-3 steps.

3. Workflow

**Complete all steps in order; do not break mid-flow.**

Step 1: Start profiling

Before starting, define lightweight success criteria with the user: which metric matters most (e.g. `totalRenderMs`, a specific commit's duration, a component's render count) and what change would be meaningful.

Start the profilers as described in §2. **Save `startedAtEpochMs` from the response** for annotations. Every later profiler and query call in this session must use the same `device_id`. Then:

• If the user asked you to profile, drive the interaction yourself (`argent-device-interact` skill).
• If the user wants to interact themselves, suggest what to do (e.g. "scroll the list", "switch tabs") and wait for their reply.

While a profiler records, interaction tools return no automatic screenshot or element tree, so the capture does not load the app. Call `screenshot` or `describe` when you need to see the screen; interaction tools still wait for the screen to settle before they return, so add no wait of your own; on an Android emulator each screenshot during a profile takes one frame in about 100 ms and does not wake the screen capture; on a physical Android device it takes about 150–200 ms and briefly wakes the device screen capture, so take them sparingly there.

Annotate every interaction

After each `gesture-tap` or `gesture-swipe`, record an annotation with `offsetMs = timestampMs - startedAtEpochMs`, using the `timestampMs` the gesture returned. Never use `Date.now()`; only the server-side timestamps. Annotate _every_ interaction, back-navigation swipes included, and pass them all to `react-profiler-analyze` in Step 3.

Step 2: Stop and collect

Call `react-profiler-stop` **and** `native-profiler-stop` in parallel (skip the native one only if you did not start it). If `fiber_renders_captured` is 0, warn the user that React commit data may be missing.

Step 3: Analyze

Call `react-profiler-analyze` with your annotations. Check the report's React Compiler and build-mode lines before proposing fixes.

If both profilers ran, also call `native-profiler-analyze`, then **you must** call `profiler-combined-report`: it surfaces correlations the individual reports miss. If it says no React commits are stored, use the native report on its own.

Step 4: Assess results

Judge whether the results actually explain what is wrong. **Do not assume an improvement always exists**; check the findings against how React Native works, give honest feedback, and be ready to change approach.

Step 5: Present findings and ask about next steps

Summarize the key findings, whether there is room for improvement, and how further work could affect performance. Then ask the user how to proceed (§2).

Step 6: Drill-down investigation (iterative)

Chain the query tools from what the report flags:

• **Slow commit** → `profiler-commit-query` `by_index` (every component, props changes, parent cascade) or `cascade_tree` (who triggered whom).
• **Slow component** → `profiler-cpu-query` `component_cpu` → `call_tree` for the hot function → read the source → propose a fix.
• **A time range** → `profiler-commit-query` `by_time_range`, or `profiler-cpu-query` `time_window`.
• **Re-render counts over the whole session** → `profil