# React Native PR Reviewer Brief

This Brief is for AI agents and human reviewers who need to review pull requests in a React Native app thoroughly and consistently.

The goal is not to praise changes or restate the diff. The goal is to find real risk before merge: bugs, regressions, poor abstractions, unsafe data flow, missing edge cases, broken UX, performance issues, and changes that will be hard to maintain.

Review from the perspective of the user, the next engineer, and production operations.

## Reviewer mindset

- Be skeptical of "small" changes. Small UI or settings updates often have data, state, navigation, analytics, notification, or permission consequences.
- Prefer correctness over style commentary.
- Treat every PR as a behavior change, not just a code change.
- Look for what can break in real usage: slow networks, app backgrounding, stale caches, partial data, denied permissions, repeat taps, race conditions, and back navigation.
- Avoid vague feedback like "clean this up." Point to a concrete risk, consequence, and better direction.

## Primary review priorities

Review in this order:

1. User-facing correctness
2. Data integrity and state consistency
3. React Native lifecycle and platform behavior
4. Error handling and recovery
5. Navigation and deep-link behavior
6. Performance and rendering
7. Test coverage and verification
8. Readability and maintainability

## What good review feedback looks like

Good feedback is:

- Specific about the problem
- Tied to behavior, not preference
- Clear about impact
- Actionable

Template:

- What can go wrong
- When it happens
- Why it matters
- What should change or be verified

Example:

- "This updates local UI state before the Firestore write completes. If the request fails, the toggle will look enabled even though the backend still has it disabled. We should either roll back on failure or derive the value from the mutation result."

## Review checklist for React Native PRs

### 1. Product behavior and UX

Check:

- Does the screen do what the PR claims?
- Are loading, empty, success, and error states all handled?
- Does the UI stay correct after repeated taps, quick navigation, pull-to-refresh, or returning from background?
- If a setting or preference changes, is the behavior change actually reflected throughout the app?
- Are destructive actions reversible, confirmed, or clearly communicated?
- Does the copy match the behavior?
- Are disabled states, placeholders, and transitions clear enough for real users?

Common misses:

- A toggle updates visually but does not persist
- A list item looks updated until refetch resets it
- A modal closes before the mutation fails
- A success path works but denied-permission or empty-state paths are broken

### 2. Data flow and source of truth

Check:

- What is the source of truth: local state, Redux, React Query, Firestore snapshot, navigation params, or persisted storage?
- Does the PR introduce duplicated state that can drift?
- Are query keys correct and stable?
- Are caches invalidated or updated intentionally after mutations?
- Are optimistic updates safe, or can they leave stale UI behind?
- If app state is persisted, are we storing only what should survive restarts?
- Are date conversions, document IDs, and nullable fields handled correctly?

Look especially for:

- Local state shadowing server state
- Firestore reads/writes that assume documents always exist
- Query functions that depend on non-null values before `enabled` fully protects them
- Redux state being used for remote data that would be safer in React Query
- Persistence clearing or reset flows that are incomplete

### 3. Async behavior, effects, and lifecycle

Check:

- Does `useEffect` have the right dependencies?
- Is a dependency intentionally omitted, and if so, is the closure still safe?
- Are subscriptions cleaned up?
- Can the code run twice safely if a component remounts?
- Can background/foreground transitions cause duplicate calls or stale state?
- Are permission checks and token refreshes resilient across auth changes?
- Could an async callback set state after unmount?

React Native-specific pitfalls:

- AppState listeners not cleaned up
- Notification listeners stacking across remounts
- Auth listeners firing sign-out/sign-in transitions in unexpected order
- Multiple providers triggering the same boot logic
- Navigation side effects running before the navigator is ready

### 4. Permissions, notifications, and device capabilities

Check:

- What happens when permission is not determined, denied, limited, or revoked later?
- Does the UI explain what to do next when access is denied?
- Are push tokens saved, refreshed, and removed correctly?
- If a preference controls notifications, is the backend behavior aligned with the client UI?
- Are device settings links used where appropriate?
- Are platform-specific assumptions called out for iOS vs Android?

Common misses:

- Permission requested on every mount
- Settings screens that assume the OS permission and backend preference mean the same thing
- Badge counts or local notifications not being cleared consistently
- Token registration happening before auth or user state is ready

### 5. Navigation, deep links, and screen contracts

Check:

- Are route params typed correctly?
- Does the screen behave if opened from a deep link instead of standard navigation?
- Are initial route assumptions stable across auth and onboarding transitions?
- Could navigation happen while required data is still loading?
- Do modal screens close safely on mutation failure?
- Are back behaviors intuitive after auth, onboarding, or settings changes?

Common misses:

- Screen assumes a param exists but type allows `undefined`
- Deep links bypass setup done in another screen
- Navigation analytics fire with the wrong screen name
- Initial route logic works only on cold launch, not after state changes

### 6. Rendering and performance

Check:

- Does the PR add unnecessary re-renders?
- Are large lists rendered efficiently?
- Are inline functions or object literals being passed in hot paths where it matters?
- Are expensive transforms repeated every render?
- Is derived data memoized only when it actually reduces work?
- Are images, animations, or gesture-heavy screens likely to hitch on low-end devices?

In review, prioritize real costs over blanket rules. Do not ask for `useMemo` or `useCallback` everywhere. Ask only when a render path is clearly hot or unstable.

Watch for:

- FlatList items doing too much work in `renderItem`
- State updates that trigger broad provider rerenders
- Nested providers adding boot-time overhead
- Unbounded cache lifetimes or oversized persisted data

### 7. Error handling and observability

Check:

- What happens when the network call fails?
- Are errors surfaced to the user when needed?
- Are silent failures acceptable here?
- Are analytics/crash reporting calls safe and useful?
- Are we logging enough context to debug production issues without leaking sensitive data?

Look for:

- `await` calls without failure handling in user actions
- Fire-and-forget writes that affect visible state
- Errors sent to crash reporting without useful metadata
- `console.log` left in production paths
- Cleanup flows that can fail silently and leave stale local state

### 8. Architecture and maintainability

Check:

- Is the logic in the right layer: screen, hook, provider, service, query, or store?
- Does the PR increase coupling across navigation, data, and UI layers?
- Are names clear and domain-accurate?
- Does the abstraction reduce duplication, or just move it?
- Will the next reviewer understand where behavior lives?

Prefer:

- Screens focused on composition
- Hooks focused on reusable stateful behavior
- Services focused on IO
- Query hooks focused on fetching/caching
- Store state reserved for app-wide client state, not every remote resource

Push back on:

- Business logic hidden inside JSX trees
- Side effects split across unrelated hooks with no obvious ownership
- "Helper" abstractions that make behavior harder to trace
- New global state when local or query state would do

## Special guidance for common PR types

### Settings and preference PRs

Review these as full-stack behavior changes, even if the diff is tiny.

Check:

- Does the UI state match backend state after refresh?
- Is there a missing default when the preference doc does not exist yet?
- What happens if the update fails?
- Do permission state and preference state conflict?
- Are all related notification or feature types covered, not just the one added in the UI?

### List and feed PRs

Check:

- Pagination cursor correctness
- Duplicate items between pages
- Empty-state correctness
- Pull-to-refresh and stale cache behavior
- Sorting consistency after create/update/delete
- List key stability

### Auth and onboarding PRs

Check:

- Sign-in, sign-out, and reauthentication transitions
- Persistence reset behavior
- Token cleanup
- Navigation resets
- Behavior when user metadata is missing or partially created

### Provider and app boot PRs

Check:

- Provider ordering assumptions
- Whether boot-time side effects run more than once
- Whether app startup can deadlock on a loading state
- Whether analytics/crash setup depends on user state that may not exist yet

### Firestore or backend-integration PRs

Check:

- Existence checks before `update`
- Batch/transaction correctness
- Date serialization/deserialization
- Partial document safety
- Whether security-rule assumptions are implicit in the client

## Red flags that deserve close attention

- `enabled` guards plus non-null assertions like `id!`
- Effects with disabled exhaustive-deps and no explanation
- Mutations with no rollback or refetch strategy
- UI that returns `null` during pending state without a user-visible fallback
- Multiple state systems representing the same remote fact
- New provider-level side effects
- Settings toggles that do not expose failure or loading state
- Firestore `update` on docs that may not exist yet
- Analytics or crash logging added without checking privacy or usefulness
- PRs that change navigation, auth, or notifications without tests or manual verification notes

## What to ask for in tests

Ask for tests when the PR changes:

- Auth flows
- Onboarding routing
- Notification preferences or permission behavior
- Query cache update logic
- Reducer behavior
- Deep links
- Error handling branches
- Transform functions that map Firestore data into app state

Useful test types:

- Unit tests for reducers, helpers, and data transforms
- Hook tests for query/mutation state behavior
- Screen tests for loading, success, error, and empty states
- Manual QA notes for OS permissions, push notifications, or navigation flows that are hard to automate

If automated tests are not practical, ask for explicit manual verification steps.

## How to write the final review

Start with findings, ordered by severity:

- Broken behavior or likely bug
- State consistency risk
- Missing edge case
- Performance or maintainability concern
- Missing verification

For each finding include:

- File or area
- Risk
- Why it matters
- Expected fix or validation

Then include:

- Open questions
- Assumptions
- Short summary only if helpful

Do not bury the findings under compliments or a long recap.

## Example review prompts for an AI reviewer

Use prompts like:

- "Review this React Native PR for bugs, regressions, lifecycle issues, state consistency, navigation risks, notification/permission edge cases, and missing tests. Prioritize findings over summary."
- "Focus on whether this settings PR keeps UI state, backend state, and OS permission state consistent."
- "Review this feed/list change for pagination correctness, cache behavior, rendering cost, and duplicate or stale data risks."
- "Review this auth/navigation PR for startup race conditions, persistence issues, and wrong-route edge cases."

## Bottom line

A strong React Native PR review does not stop at style, naming, or formatting. It asks:

- Will this work on a real device?
- Will it stay correct after async work, app lifecycle changes, and navigation?
- Does UI state still match server state?
- Is failure handled well?
- Will the next engineer be able to reason about it?

That is the standard for approval.