/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.

2. Tool Overview

React Profiler (Hermes / React commits)

| Tool | Purpose | | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `react-profiler-start` | Start CPU sampling + inject React commit-capture hook. Optional: `sample_interval_us` (default 100). | | `react-profiler-stop` | Stop recording; stores cpuProfile + commitTree in session. | | `react-profiler-status` | **Call if you were interrupted in the middle of the flow, never in another scenario** (debugger drop, Metro reload, pause, subagent handoff, any doubt). Returns `session_status: "active" \| "taken_over" \| "stopped" \| "no_react_runtime"`. Side-effect free. | | `react-profiler-analyze` | Run pipeline -> report with CPU-enriched hot commits, sorted by `totalRenderMs` DESC. Saves raw data to disk. | | `react-profiler-component-source` | AST lookup: file, line, memoization status, 50 lines of source for a component. | | `react-profiler-renders` | Live fiber walk: render counts + durations per component (no profiling session required). | | `react-profiler-fiber-tree` | Live fiber walk: full component hierarchy as JSON. |

Drill-Down Query Tools (call after analyze)

| Tool | Purpose | | -------------------------- | -------------------------------------------------------------------------------------------- | | `profiler-cpu-query` | Targeted CPU investigation: top functions, time-windowed CPU, call trees, per-component CPU. | | `profiler-commit-query` | Targeted commit investigation: by component, time range, commit index, or cascade tree. | | `profiler-stack-query` | iOS Instruments drill-down: hang stacks, function callers, thread breakdown, leak details. | | `profiler-combined-report` | Cross-correlated report when both React Profiler and native profiler ran in parallel. | | `profiler-load` | List and reload previous profiling sessions from disk for re-investigation with query tools. |

For native profiling (CPU hotspots, UI hangs, memory leaks), see the `argent-native-profiler` skill.

---

3. Agent Behavior Guidelines

Follow these rules throughout the profiling workflow:

• Start `react-profiler-start` and `native-profiler-start` in parallel (two tool calls in one message). Both need `device_id`; use the same UDID for both so their data can be correlated later. This gives best coverage.
• If the user only wants native profiling, use the `argent-native-profiler` skill workflow. Only skip `native-profiler-start` if the user has **already explicitly said** they don't want native profiling in this session

After analysis: ask about next steps

After presenting the analysis report, always ask the user what they want to do next. Present these options:

1. **Investigate further** — drill down into specific findings using query tools (CPU call trees, commit cascades, hang stacks, etc.) to identify root causes with confidence before making changes. 2. **Implement fixes** — apply changes based on the current findings, then re-profile to measure whether the metric changed (improved, regressed, or stayed flat). 3. **Done for now** — accept the report as-is.

Do NOT silently move on after the report. The report is the starting point, not the end — query tools exist specifically to let you dig deeper into anything the report flags.

During investigation: use query tools proactively

When drilling down, chain query tool calls based on what you find:

• A hot commit -> `profiler-commit-query` mode=`by_index` to see all components -> `profiler-cpu-query` mode=`component_cpu` for the slowest one -> `profiler-cpu-query` mode=`call_tree` for the hot function -> read the source file -> propose a fix.
• A memory leak -> `profiler-stack-query` mode=