Argent React Native Optimization

Rules

• Do not apply shotgun optimizations. Measure first, define what "good enough" looks like (target metric + threshold), fix the top offender, re-measure honestly.
• Quick scan — react-profiler-renders for a live render count table. Identifies hot components instantly.
• Deep measure — load argent-react-native-profiler skill. react-profiler-start → interact → react-profiler-stop → react-profiler-analyze.
• Inspect — react-profiler-component-source per finding. react-profiler-fiber-tree to trace component ancestry and render cost.
• Verify correctness - before fixing, recollect information from steps above and make a logical conclusion whether the approach is worth undertaking.
• Fix — apply one fix. Validate with debugger-evaluate before committing.
• Re-measure — report whether the target metric improved, regressed, or stayed flat. Check for regressions in other areas. If no net benefit or unacceptable tradeoffs, revert.
• Profile for discovery, not only verification. Use the profiler to find issues static analysis missed, not only to confirm fixes.
• One fix per cycle for architectural changes. Mechanical batch fixes (inline styles, index keys) can be grouped — re-profile once after the batch. When the measurement involves device interaction, record it as a flow (argent-create-flow skill) before the first run so all subsequent cycles replay identical steps.
• React Compiler: if react-profiler-analyze reports reactCompilerEnabled: true, do NOT propose useCallback/useMemo/React.memo unless you confirmed compiler bail-out via react-profiler-fiber-tree (absent useMemoCache).
• Sub-agents: Phases 1–2 dispatch sub-agents — one per file for lint results, one per checklist item for semantic. Sub-agents CANNOT touch the device - all profiling and E2E verification must happen in the main agent.

Pipeline

Lint and semantic sweeps catch deterministic issues cheaply. Profiling finds runtime bottlenecks that static analysis misses. Do both.

Copy this checklist into your TODO list:

Optimization Progress:
- [ ] Phase 1: Lint sweep (deterministic — catch mechanical issues without a running app)
- [ ] Phase 2: Semantic sweep (judgment — memoization, lists, animations, etc.)
- [ ] Phase 3: Baseline profile (find real bottlenecks, fix top offenders)
- [ ] Phase 4: Verify no regressions (crashes, errors, red screens)

Phase 1: Lint sweep

Run ESLint once at the project root with a comprehensive RN performance ruleset. Dispatch sub-agents to fix results — one per file. See references/lint-rules.md for ruleset and procedure.

Phase 2: Semantic sweep

Review each area requiring judgment — memoization, list rendering, animations, async patterns, effect cleanup, state hygiene, context architecture. Dispatch one sub-agent per checklist item. See references/semantic-checklist.md for full checklist.

Phase 3: Visual profiling

1. Load argent-react-native-profiler skill, start dual profiling 2. Exercise key user flows (navigate screens the user specified, or all major flows) 3. Analyze with react-profiler-analyze + native-profiler-analyze + profiler-combined-report 4. Cross-reference profiling results with Phase 1–2 findings 5. Fix highest-impact issues. Re-profile after architectural changes; batch mechanical fixes. If a recorded flow breaks after a fix (e.g., UI layout changed), follow argent-create-flow skill to repair the flow rather than silently discarding it.

Phase 4: Verify no regressions

Navigate every screen and UI flow within scope, confirm each renders without errors. If no scope was specified, verify the entire app — cover all reachable screens via argent-device-interact. Use debugger-log-registry to check for runtime errors and take screenshots to check for red/yellow error screens. Check for regressions introduced by fixes (e.g., fewer re-renders but higher CPU, or new jank in a different screen). Main agent only.

App-wide optimization

1. Phase 1: run lint centrally (one command), dispatch sub-agents to fix per-file in parallel 2. Phase 2: one sub-agent per checklist item for semantic sweep 3. Phase 3: main agent profiles top offending screens; fixes architectural issues top-down 4. Phase 4: main agent navigates all screens to verify nothing crashes

After the entire run, run lint again to verify no new issues were introduced with your changes. This also helps ensure you haven't missed any issues which could've been fixed.

Fix Reference

Match profiler findings and semantic sweep results to concrete fixes.

Phase 1: Lint Rules

Run once at the project root. Catches mechanical issues deterministically. Install missing plugins before running: npm install --save-dev eslint-plugin-react-perf.

Rules

Performance (eslint-plugin-react-perf)

React (eslint-plugin-react)

React Native (eslint-plugin-react-native)

Hooks (eslint-plugin-react-hooks)

Error handling (ESLint core)

Procedure

1. Check if the project has an existing ESLint config. 2a. If yes, extend it with missing rules from above. 2b. If no config, create a temporary .eslintrc.json with all rules above. 2. Run: npx eslint --format json <src_dir> — replace <src_dir> with the project's JS/TS source root (check package.json scripts or look for src/, app/, lib/) 3. Parse output into: file:line -> rule -> message.

Phase 2: Semantic Sweep

Work through each area. Do not skip. See fix-reference.md for concrete fix patterns per finding.

Checklist

Memoization

Check every exported function component: is it rendered in a list, a frequently-updating parent, or a context consumer? If yes and props are stable, wrap in React.memo. Check context providers for unstable value props. Skip React.memo if React Compiler is active.

List rendering

Check all list-like rendering: ScrollView+map, manually iterated arrays, deeply nested FlatLists. Verify lists use virtualization (FlatList/FlashList), stable keys, and proper item sizing.

Animations

Check all animation code against current library best practices. Prefer Reanimated over the Animated API. Check for JS-thread animation bottlenecks (requestAnimationFrame loops, state-driven animations).

Async patterns

Check for sequential await calls that could be Promise.all. Check for missing AbortController / cancellation on unmount. Check for fetch waterfalls (parent fetches → child fetches → grandchild fetches).

Effect cleanup

Check all useEffect hooks that create timers, listeners, or subscriptions. Verify each returns a cleanup function. Check for effects missing dependency arrays (runs every render).

State hygiene

Check for unused state (set but never rendered), unbounded state growth (arrays/objects that grow without cap), and derived state that should be computed with useMemo instead.

Monolithic context

Flag but do NOT auto-fix. Report as architectural recommendation.