docs: guide bounded react devtools profiling (#548)

Author: thymikee

README.md

@@ -170,7 +170,7 @@ Run:
 - Capture a baseline `snapshot -i`, screenshot, and `perf --json` sample.
 - Exercise Home, Catalog, product detail, Checkout, and Settings. Re-snapshot after each mutation and use refs/selectors from fresh snapshots.
 - Capture at least one overlay-ref screenshot, one normal screenshot, one short video recording for a meaningful flow, logs marks around any issue, and trace output if a runtime symptom needs diagnostics.
-- Run focused performance checks: compare `perf --json` before and after a navigation or form flow; if React DevTools connects, capture profile slow/rerender output. If it cannot connect, include the status and continue.
+- Run focused performance checks: compare `perf --json` before and after a navigation or form flow; if React DevTools connects, use one bounded first-pass profile survey (`slow --limit 5`, `rerenders --limit 5`, and `timeline --limit 20` only when timing matters), then drill into a specific `@c` ref with `profile report`. If it cannot connect, include the status and continue.
 - Close the session so the `.ad` replay is written.
 
 Report:

src/utils/__tests__/args.test.ts

@@ -897,6 +897,7 @@ test('usageForCommand resolves workflow help topic', () => {
   assert.match(help, /metro prepare --kind expo/);
   assert.match(help, /help react-devtools/);
   assert.match(help, /help react-native/);
+  assert.doesNotMatch(help, /agent-device react-devtools profile/);
 });
 
 test('workflow help keeps common copyable command forms', () => {
@@ -975,7 +976,14 @@ test('usageForCommand resolves react-devtools help topic', () => {
   );
   assert.match(help, /render causes and changed props\/state\/hooks/);
   assert.match(help, /logs clear --restart before the first logs mark/);
+  assert.match(help, /one bounded first-pass survey/);
+  assert.match(help, /profile slow --limit 5 once/);
+  assert.match(help, /profile rerenders --limit 5 once/);
+  assert.match(help, /profile timeline --limit 20 only when commit timing matters/);
+  assert.match(help, /Do not repeatedly raise broad profile slow limits/);
+  assert.match(help, /profile report unless you have a specific target/);
   assert.match(help, /agent-device logs mark "before catalog search"/);
+  assert.match(help, /agent-device react-devtools profile timeline --limit 20/);
   assert.match(help, /Do not write agent-devtools/);
   assert.match(help, /agent-device network dump --include headers/);
   assert.match(help, /@c refs reset after reload\/remount/);

src/utils/command-schema.ts

@@ -346,16 +346,6 @@ React Native dev loop:
   If apps lookup misses the project but shows Expo Go/dev-client and a project URL is available, open the URL/host shell; if no URL is available, ask instead of inventing an app id.
   Expo Dev Client/development builds: open the installed dev-client app id/name; if a dev-client URL is provided, open that URL next. For Metro setup use metro prepare --kind expo.
 
-React DevTools minimum loop:
-  Keep the agent-device react-devtools prefix on every React DevTools command:
-    agent-device react-devtools status
-    agent-device react-devtools wait --connected
-    agent-device react-devtools profile start
-    interact with normal agent-device commands
-    agent-device react-devtools profile stop
-    agent-device react-devtools profile slow --limit 5
-    agent-device react-devtools profile rerenders --limit 5
-
 Escalate:
   help debugging       logs, network, alerts, traces, flaky runtime failures
   help react-devtools  React Native performance, profiling, props/state/hooks, slow renders, rerenders
@@ -447,15 +437,16 @@ Profiling loop:
   3. Start profiling immediately before the interaction.
   4. Drive the interaction with normal agent-device commands and mark before/after the repro when timing matters.
   5. Stop profiling.
-  6. Inspect slow components and rerenders.
-  7. Use profile report @cN for render causes and changed props/state/hooks; use get component @cN for current props/state/hooks.
+  6. Make one bounded first-pass survey: profile stop for the summary, profile slow --limit 5 once, profile rerenders --limit 5 once, and profile timeline --limit 20 only when commit timing matters.
+  7. Use profile report @cN for targeted render causes and changed props/state/hooks; use get component @cN for current props/state/hooks.
 
 Rules:
   Every React DevTools command is an agent-device subcommand: agent-device react-devtools ...
   Do not write agent-devtools, agent-react-devtools, or bare react-devtools commands in final command plans.
   Start with get tree --depth 3 or find <name>; use find --exact when fuzzy results are noisy.
   @c refs reset after reload/remount. After reload, wait --connected and inspect again.
   Keep the profile window narrow; unrelated navigation makes render data noisy.
+  Do not repeatedly raise broad profile slow limits such as --limit 50, --limit 200, or --limit 500. Drill into a specific @c ref with profile report unless you have a specific target that needs more rows.
   For network evidence, use agent-device network dump --include headers; headers is not a positional argument.
   For cross-platform validation with explicit device selectors, prefer isolated --state-dir and restart react-devtools between platforms.
   Remote Android and iOS bridge runs normally through agent-device react-devtools; the CLI keeps the needed local service tunnel alive until agent-device react-devtools stop or disconnect. Expo support depends on the SDK's bundled React Native runtime.
@@ -472,6 +463,7 @@ Example:
   agent-device react-devtools profile stop
   agent-device react-devtools profile slow --limit 5
   agent-device react-devtools profile rerenders --limit 5
+  agent-device react-devtools profile timeline --limit 20
   agent-device react-devtools profile report @c5
   agent-device network dump --include headers
 

test/skillgym/suites/agent-device-smoke-suite.ts

@@ -203,6 +203,13 @@ const RAW_COORDINATE_TARGET =
   /(?:^|\n)(?:agent-device\s+)?(?:click|fill|press)\s+-?\d+(?:\.\d+)?\s+-?\d+(?:\.\d+)?/i;
 const PSEUDO_ASSERTION_COMMAND = /(?:^|\n)\s*(?:assert|assertVisible|waitFor|waitForText)\b/i;
 const COMPACT_RECT_SNAPSHOT = /snapshot\b(?=[^\n]*(?:-c\b|--compact\b))(?=[^\n]*(?:--json|--raw))/i;
+const BOUNDED_PROFILE_SLOW = /react-devtools\s+profile\s+slow\b[^\n]*--limit\s+(?:5|10)\b/i;
+const BOUNDED_PROFILE_RERENDERS =
+  /react-devtools\s+profile\s+rerenders\b[^\n]*--limit\s+(?:5|10)\b/i;
+const BOUNDED_PROFILE_TIMELINE =
+  /react-devtools\s+profile\s+timeline\b[^\n]*--limit\s+(?:10|20)\b/i;
+const BROAD_PROFILE_SLOW_LIMIT =
+  /react-devtools\s+profile\s+slow\b[^\n]*--limit\s+(?:[5-9]\d|[1-9]\d{2,})\b/i;
 const IOS_EXPO_GO_OPEN =
   /(?:^|\n)(?:agent-device\s+)?open\s+["']Expo Go["']\s+["']?exp:\/\/127\.0\.0\.1:8081["']?/i;
 
@@ -1124,10 +1131,36 @@ const SKILL_GUIDANCE_CASES: Case[] = [
       plannedCommand('react-devtools profile start'),
       /catalog-search/i,
       plannedCommand('react-devtools profile stop'),
-      plannedCommand('react-devtools profile slow'),
-      plannedCommand('react-devtools profile rerenders'),
+      BOUNDED_PROFILE_SLOW,
+      BOUNDED_PROFILE_RERENDERS,
     ],
-    forbiddenOutputs: [plannedCommand('snapshot'), plannedCommand('perf')],
+    forbiddenOutputs: [
+      plannedCommand('snapshot'),
+      plannedCommand('perf'),
+      BROAD_PROFILE_SLOW_LIMIT,
+    ],
+  }),
+  makeCase({
+    id: 'react-devtools-bounded-profile-survey',
+    contract: [
+      'App name: Agent Device Tester',
+      'React Native DevTools is connected',
+      'Interaction to profile: expand the checkout totals panel',
+      'Totals panel selector: id="checkout-totals"',
+      'Need a compact performance report with initial summary, slow components, rerender counts, and commit timing',
+      'Do not over-fetch broad profile tables while looking for offenders',
+    ],
+    task: 'Plan a bounded first-pass React DevTools profile workflow for the checkout totals interaction.',
+    outputs: [
+      plannedCommand('react-devtools wait'),
+      plannedCommand('react-devtools profile start'),
+      /checkout-totals/i,
+      plannedCommand('react-devtools profile stop'),
+      BOUNDED_PROFILE_SLOW,
+      BOUNDED_PROFILE_RERENDERS,
+      BOUNDED_PROFILE_TIMELINE,
+    ],
+    forbiddenOutputs: [BROAD_PROFILE_SLOW_LIMIT],
   }),
   makeCase({
     id: 'react-devtools-exact-component-inspect',
@@ -1192,11 +1225,17 @@ const SKILL_GUIDANCE_CASES: Case[] = [
       /(?:5000|10000|12000|15000|20000)/i,
       /logs mark\b[^\n]*(?:after|end|verified|diagnostics|loaded)/i,
       plannedCommand('react-devtools profile stop'),
-      plannedCommand('react-devtools profile slow'),
-      plannedCommand('react-devtools profile rerenders'),
+      BOUNDED_PROFILE_SLOW,
+      BOUNDED_PROFILE_RERENDERS,
       /network dump\b[^\n]*(?:--include headers|\bheaders\b|\ball\b)/i,
     ],
-    forbiddenOutputs: [RAW_COORDINATE_TARGET, /cat .*log/i, /alert wait/i, /agent-devtools/i],
+    forbiddenOutputs: [
+      RAW_COORDINATE_TARGET,
+      /cat .*log/i,
+      /alert wait/i,
+      /agent-devtools/i,
+      BROAD_PROFILE_SLOW_LIMIT,
+    ],
   }),
   makeCase({
     id: 'gesture-swipe-carousel',

website/docs/docs/commands.md

@@ -594,12 +594,16 @@ agent-device react-devtools profile start
 agent-device react-devtools profile stop
 agent-device react-devtools profile slow --limit 5
 agent-device react-devtools profile rerenders --limit 5
+agent-device react-devtools profile timeline --limit 20
+agent-device react-devtools profile report @c5
 ```
 
 - `react-devtools` dynamically runs pinned `agent-react-devtools@0.4.0` through npm and passes arguments through 1:1.
 - The first run may download the pinned package from npm; later runs can reuse the npm cache.
 - `agent-device` global flags work before or after `react-devtools`. Use `--` before downstream flags only when they intentionally share an `agent-device` global flag name.
 - Use it when a React Native workflow needs component hierarchy, props, state, hooks, render causes, slow components, or re-render counts.
+- For profiling, keep the window narrow and make one bounded first-pass survey: use the `profile stop` summary, run `profile slow --limit 5` and `profile rerenders --limit 5` once, add `profile timeline --limit 20` only when commit timing matters, then drill into a specific `@c` ref with `profile report`.
+- Do not repeatedly raise broad `profile slow` limits such as `--limit 50`, `--limit 200`, or `--limit 500` unless you have a specific target that needs more rows.
 - Keep using `snapshot`, `press`, `fill`, `logs`, `network`, and `perf` for device/app runtime evidence. Use `react-devtools` for React internals.
 - For React Native apps, overlays, Metro/Fast Refresh blockers, and routing to React DevTools or debugging evidence, start with `agent-device help react-native`.
 - On Android, permission prompts are visible UI; use `snapshot -i` and press visible `Allow`/`Deny` controls instead of `alert wait`. Do not use `settings permission` to answer a dialog already on screen; reserve it for setup or resetting permission state before a flow.

website/docs/docs/debugging-profiling.md

@@ -26,12 +26,13 @@ agent-device react-devtools profile start
 agent-device react-devtools profile stop
 agent-device react-devtools profile slow --limit 5
 agent-device react-devtools profile rerenders --limit 5
+agent-device react-devtools profile timeline --limit 20
 agent-device react-devtools profile report @c5
 ```
 
 `agent-device` remains centered on the device and app runtime layer. The `react-devtools` command dynamically runs pinned `agent-react-devtools` commands for React internals.
 
-For React Native apps, overlays, Metro/Fast Refresh blockers, and routing to React DevTools or debugging evidence, start with `agent-device help react-native`. For slow-flow investigations, combine `help react-devtools` for the narrow React profile window with `help debugging` for log markers, network evidence, traces, and perf samples.
+For React Native apps, overlays, Metro/Fast Refresh blockers, and routing to React DevTools or debugging evidence, start with `agent-device help react-native`. For slow-flow investigations, combine `help react-devtools` for the narrow React profile window with `help debugging` for log markers, network evidence, traces, and perf samples. Make one bounded first-pass survey with the `profile stop` summary, bounded `slow` and `rerenders` tables, and `timeline` only when commit timing matters; then drill into a specific `@c` ref with `profile report` instead of repeatedly raising broad `profile slow` limits.
 
 React Native warning/error overlays belong to the app run. Treat them as findings or blockers: capture them, check `react-devtools errors` when connected, dismiss visible `Dismiss`/`Close` controls only when unrelated, then re-snapshot and report the overlay.