gh pr view <pr-number> --repo Shopify/flash-list
gh pr diff <pr-number> --repo Shopify/flash-list
gh pr view <pr-number> --repo Shopify/flash-list --comments

From a local branch

git log main..HEAD --oneline
git diff main...HEAD

Identify:

What changed: which files, which functions
Why: what bug is fixed or feature added
Risk areas: layout, measurement, RTL, scroll, recycling

Step 2 — Run Automated Checks

All three must pass:

yarn test
yarn type-check
yarn lint

Fixture type-check (if fixture files changed)

Root yarn type-check only covers src/ — the fixture has a separate tsconfig.json. Root yarn lint does cover fixture files.

If any files in fixture/react-native/ were modified, also run:

git diff main...HEAD --name-only | grep 'fixture/react-native/'

# If matches found:
cd fixture/react-native && yarn build   # tsc -b — catches type errors in fixture code

E2E Tests

Run E2E tests if any of these changed in the PR/branch:

E2E test files (*.e2e.*)
Example/sample screens in fixture/react-native/src/
New example screens added

# Check if e2e-relevant files were changed
git diff main...HEAD --name-only | grep -E '\.e2e\.|fixture/react-native/src/'

# If yes, run e2e tests on iOS
yarn e2e:ios

E2E tests use Detox. The yarn e2e:ios script handles both build and test.

Warning: E2E builds a release app that replaces the debug app on the simulator. After running E2E, rebuild debug to continue interactive testing:

cd fixture/react-native && yarn react-native run-ios

If tests fail, investigate before proceeding to device testing.

Step 3 — Build

CRITICAL: The fixture app uses compiled output from dist/. Source changes in src/ have NO effect until built.

yarn build   # runs tsc -b

Install the fixture app only if needed

Before building the native app, check if it's already installed on the simulator. Only build if it's not installed:

xcrun simctl get_app_container booted org.reactjs.native.example.FlatListPro 2>/dev/null

If the command succeeds (returns a path): the app is installed. Skip run-ios — just relaunch it.
If the command fails: the app is not installed. Build and install it:

cd fixture/react-native && yarn react-native run-ios

Relaunch the app

After yarn build, relaunch the app (kill + reopen) so Metro serves the new bundle:

agent-device close --platform ios
xcrun simctl launch --terminate-running-process <UDID> org.reactjs.native.example.FlatListPro
agent-device open "FlatListPro" --platform ios

Find the simulator UDID with:

xcrun simctl list devices | grep Booted

Step 4 — Test on Device (LTR)

Navigate to affected screens

Use the agent-device skill to navigate and take screenshots. Screens are listed on the Examples page. Common ones:

Screen	What to check
Sticky Header Example	Headers pin correctly, no duplicate overlays
Horizontal List	Items scroll, header reachable, initialScrollIndex works
Grid	Multi-column layout correct
Masonry	Variable heights, columns balanced
Chat	Bottom-rendering, prepend behavior
Contacts	Section headers, fast scrolling
Grid with Separator	Last row items same height, separators between rows only

Smoke test

Navigate to each affected screen, scroll through content, verify no visual regressions.

Step 4b — Test on Android (if available)

If an Android emulator is available (e.g., on the android-agent CI runner), test there too. Android uses a native RecyclerView bridge so behavior can differ from iOS.

Build and install

yarn build
cd fixture/react-native && yarn react-native run-android

Navigate and verify

Use agent-device with --platform android --session droid:

agent-device snapshot -i -c --json --session droid
agent-device press <x> <y> --session droid
agent-device screenshot /tmp/android-screen.png --session droid

Android-specific things to check

RecyclerView scroll behavior matches iOS
Items render correctly (no blank/recycled artifacts)
Sticky headers work with native scroll
onEndReached / onStartReached fire at the same thresholds as iOS

Step 5 — Test RTL

How to enable RTL properly

The ONLY reliable method: change fixture/react-native/index.js:

// Change this:
I18nManager.forceRTL(false);
// To this:
I18nManager.forceRTL(true);

Then kill and relaunch the app (a JS reload is NOT sufficient):

agent-device close --platform ios
xcrun simctl launch --terminate-running-process <UDID> org.reactjs.native.example.FlatListPro
agent-device open "FlatListPro" --platform ios

Do NOT use:

DevSettings.reload() — does not properly apply RTL
The Debug screen toggle — unreliable, layout may not fully flip

RTL verification checklist

Text is right-aligned on the Examples screen
Navigation back chevron is on the RIGHT side
HorizontalList: items ordered right-to-left (Item 0 on right, higher items on left)
HorizontalList: header is reachable by swiping right-to-left (toward the logical start)
Grid: columns mirrored
StickyHeaders: headers pin correctly
Chat: messages align correctly
Masonry: layout mirrors properly

RTL scrolling on horizontal lists

In RTL, the scroll direction is reversed:

Swipe right-to-left (finger moves left): reveals content toward the logical START (header, Item 0)
Swipe left-to-right (finger moves right): reveals content toward the logical END (higher items)

Use agent-device swipe with coordinates at the list center:

# Swipe right-to-left at y=30% (list center on HorizontalList screen)
agent-device swipe 350 256 50 256 --platform ios

Always revert RTL when done

I18nManager.forceRTL(false);

Step 6 — Verify `firstItemOffset` Values (for layout/measurement changes)

If the PR touches measureLayout, measureParentSize, firstItemOffset, or RecyclerView.tsx layout logic, verify the actual runtime values match expected values.

Expected values (verified on RN 0.84 Fabric)

Scenario	`firstItemOffset` (adjusted)
Vertical, no header	0
Vertical, with ListHeaderComponent	headerHeight
Vertical, content above FlashList	0 (NOT the parent's y position)
Horizontal LTR, with header	headerWidth
Horizontal RTL, with header (1st render)	headerWidth
Horizontal RTL, with header (stable)	headerWidth

How to capture runtime values

console.log does NOT work on Fabric/Hermes (output goes to CDP debugger, not Metro).

Use a local HTTP server instead:

# Terminal 1: start server
node -e "
const http=require('http'),fs=require('fs');
http.createServer((q,r)=>{
  if(q.method==='POST'){let b='';q.on('data',c=>b+=c);q.on('end',()=>{
    fs.appendFileSync('/tmp/rv-debug.log',b+'\n');console.log(b);r.end('ok');})}
  else r.end('ok');
}).listen(9876,()=>console.log('on :9876'));
"

Add to source (remember to remove after):

try {
  fetch("http://localhost:9876", {
    method: "POST",
    body: JSON.stringify({ tag: "myDebug", ...values }),
  }).catch(() => {});
} catch (e) {}

Then rebuild (yarn build), relaunch, navigate, and read /tmp/rv-debug.log.

`measureParentSize` x/y behavior

On RN 0.84 Fabric, view.measureLayout(view) returns x=0, y=0 (the Fabric self-measurement bug from #2017 does NOT reproduce on this version). The defensive fix that strips x/y is a no-op here but protects other RN versions.

Step 7 — Write Review Summary

After testing, provide:

Automated checks: pass/fail for test, type-check, lint
LTR behavior: which screens tested, any issues
RTL behavior: which screens tested, any issues
firstItemOffset verification (if applicable): actual vs expected values
Regression risk: low/medium/high with reasoning
Recommendation: approve, request changes, or needs more testing

Edge Cases to Test

Run through relevant entries after any fix or review. This is the single source of truth for edge case checklists — the fix-github-issue skill references this.

Layout & Measurement

Content above FlashList (another component in the same parent View)
ListHeaderComponent with variable height
stickyHeaderOffset > 0 combined with content above FlashList
Horizontal FlashList (x-axis equivalent of any vertical measurement bug)
Horizontal list with wide ListHeaderComponent — header must be reachable by scrolling
measureParentSize x/y values — on RN 0.84 Fabric these are (0,0), but on other RN versions they may be non-zero
numColumns > 1 with ItemSeparatorComponent — last row items must have same height (no separator height mismatch)
numColumns > 1 with ItemSeparatorComponent and overrideItemLayout (variable spans) — separator suppression must use layout y-coordinates, not index arithmetic

RTL (Right-to-Left)

HorizontalList in RTL — items right-to-left, header reachable by swiping right-to-left
Grid in RTL — column ordering reversed
StickyHeaderExample in RTL — header must pin to correct edge
Chat in RTL — messages align correctly
Masonry in RTL

Sticky Headers

Multiple sticky indices with content above FlashList (issue #2017 scenario)
Sticky headers with stickyHeaderOffset > 0
Sticky header transition at exact item boundary (scroll = item.y)
Sticky header when next sticky is beyond engaged indices
Sticky header + maintainVisibleContentPosition / startRenderingFromBottom
hideRelatedCell: true — overlay hides original cell without jumping

New Architecture (Fabric)

Any measureLayout/measureParentSize call — verify behaviour matches Paper
firstItemOffset after fix — confirm it equals ListHeaderComponent height/width
measureParentSize(view) returns x=0, y=0 on RN 0.84 Fabric — the #2017 bug may only manifest on other RN versions

Performance

Benchmark screen shows no FPS regression (use ManualBenchmarkExample)

Common Issues

Tests pass but device shows bug — did you yarn build and relaunch? The dist/ folder may be stale
Switched branches but behavior didn't change — dist/ is NOT rebuilt on branch switch. You MUST run yarn build after every git checkout. Verify with grep in dist/ that the expected code is present before testing.
RTL looks wrong but LTR is fine — did you set forceRTL(true) in index.js and do a full kill+relaunch?
agent-device swipe gives "drag" error — delete ~/.agent-device/ios-runner/derived/ and re-run agent-device open to rebuild the iOS runner
No console output in Metro — use the HTTP server approach (see Step 6)
Metro log location — lsof -p $(lsof -ti :8081) | grep "1w" to find where Metro stdout goes (often /private/tmp/metro_fixture.log)
RTL horizontal scroll direction is reversed — to scroll toward the logical START (header/Item 0), swipe right-to-left: agent-device swipe 350 256 50 256. To scroll toward higher items, swipe left-to-right.
Fixture app bundle ID — org.reactjs.native.example.FlatListPro. Use with xcrun simctl launch.
estimatedItemSize does not exist — this FlashList does NOT have this prop. Do not use it.
App can't connect to Metro — if the app shows a red/yellow error about connecting to the bundler, configure the port: iOS simulator Cmd+D → "Configure Bundler" → set host localhost and the correct port. Then reload.
agent-device navigation — use snapshot -i -c --json as the primary method for finding elements (returns exact coordinates). Fall back to screenshot + percentage-based press when elements aren't in the accessibility tree. See the agent-device skill for details.

Review Methodology

Always reproduce BEFORE verifying the fix

Checkout main, build (yarn build), relaunch, and reproduce the bug
Checkout the PR branch, build (yarn build), relaunch, and verify the fix
Verify dist after each branch switch: grep "expected_code" dist/path/to/file.js — if the old code is still there, the build didn't run or didn't pick up the change

Without step 1, you can't confirm the fix actually changed anything. Without verifying dist, you might test stale code on both branches and conclude "no difference" incorrectly.

Making behavior observable

When testing callback-based behavior (e.g., onStartReached, onEndReached, onViewableItemsChanged), add a visible counter to the fixture screen:

const [count, setCount] = useState(0);
// In the callback:
onStartReached={() => setCount(c => c + 1)}
// In the UI:
<View style={{ backgroundColor: count > 0 ? '#ff4444' : '#cccccc', ... }}>
  <Text>Start: {count}</Text>
</View>

This gives immediate visual feedback in screenshots without needing console.log or debug servers.

Masonry PRs — watch for sorting

Any masonry layout PR that adds Array.sort() or sorted copies is a red flag for performance. getVisibleLayouts runs on every scroll frame (60fps). O(N log N) sorting per layout change is expensive. Items within each column are naturally sorted — per-column binary search is O(log N) without sorting.

Self-Evolving Instructions

This skill is the single source of truth for testing knowledge, edge cases, and debug techniques. The fix-github-issue skill delegates here for Steps 6-7.

After each session, update this file with:

New screens or scenarios that need testing
New debug techniques discovered
Updated expected values if the codebase changes
New edge cases discovered during fixes

review-and-test

Review & Test a FlashList PR or Branch

Prerequisites

Step 1 — Understand the Change

From a PR