Remix v2 Data Flow Code Review

intent

this skill audits TypeScript route modules in a Remix v2 codebase for data-flow bugs that break SSR, revalidation, or security. use it when reviewing loader, action, shouldRevalidate, or headers exports, plus their consumers (useLoaderData, useActionData, useNavigation, useFetcher, useRevalidator, <Await>). the skill catches mutations in loaders, unvalidated FormData, leaked server fields, wrong redirect patterns, v1 holdovers (useTransition, LoaderArgs), and defer / <Suspense> mistakes that block streaming or hide errors.

inputs

• remix route module files under app/routes/ exporting loader, action, shouldRevalidate, or headers; also consumer components importing useLoaderData, useActionData, useNavigation, useFetcher, useRevalidator, or <Await> from @remix-run/react
• server runtime context (e.g. @remix-run/node, @remix-run/cloudflare, @remix-run/deno) , inferred from imports
• schema validators (zod, valibot, custom) if present in the codebase
• reference documents (loaders.md, actions.md, revalidation.md, defer-await.md) for context-specific rules
• pre-review checklist from review-verification-protocol to gate findings before submission

procedure

1. identify route modules in scope , locate all files under app/routes/ that export loader, action, shouldRevalidate, headers, or components consuming remix hooks. note the exact file path.

2. extract loader bodies , for each export async function loader or export const loader, read the full function body. check: data reads only (no mutations), params validated with invariant or schema, return value is a projected DTO (no password/token/internal fields), error cases throw Response (not strings or plain Error), 404 / auth short-circuits are explicit.

3. extract action bodies , for each export async function action or export const action, read the full function body. check: request.method handling (POST / PUT / DELETE / PATCH), request.formData() validated before use, success branch returns redirect(...) (PRG), validation errors return json({ errors }, { status: 400 }), both success and error paths are explicit (no silent return null).

4. check consumer hooks , in the component body, scan for useLoaderData, useActionData, useNavigation, useFetcher, useRevalidator. verify: type annotations use <typeof loader> / <typeof action> (not as Foo), pending state reads nav.state or fetcher.state (not v1 useTransition), formMethod comparisons are uppercase ("POST"), manual useRevalidator().revalidate() calls are not immediately after a <Form> post or fetcher.submit.

5. check shouldRevalidate exports , if present, verify: the function returns defaultShouldRevalidate by default, opt-outs are narrow and justified (e.g. conditional on formAction or currentParams), blanket return false is not used without reasoning.

6. check defer and streaming , if defer({...}) is used, verify: every promise in the payload was not awaited before passing it, every <Await> is wrapped in <Suspense>, every <Await> has an errorElement prop, no awaited data is passed to defer (antipattern).

7. run hard gates , before drafting findings, complete all five hard gates (location evidence, exemption check, type-annotation check, v1 holdover check, protocol verification). do not report issues that fail any gate.

8. cross-check with valid patterns , for each potential issue, consult the Valid Patterns (Do NOT Flag) section. confirm the code is not: useEffect reading browser-only APIs, bare Response returns for non-JSON, legitimate null loader returns, useLoaderData<typeof loader>() type annotations, return redirect(...) in actions, parent revalidation after unrelated actions, validation-error json() returns, useRevalidator for focus / polling, or SerializeFrom type changes.

9. verify context-sensitive rules , for issues in the Context-Sensitive Rules table, confirm the specific context applies before flagging (e.g. don't flag missing loader unless data is server-available and not browser-only).

10. compile findings , for each issue that passes all gates, write a finding with: repo path, line range or verbatim quote, rule violated, reason for the flag, and a reference to the applicable checklist item or reference document. output findings in order of severity (security > correctness > ergonomics).

decision points

• if the file exports loader: follow step 2 (extract and audit loader body). if the file does not, skip to step 3.
• if the file exports action: follow step 3 (extract and audit action body). if the file does not, skip to step 4.
• if the component calls useLoaderData, useActionData, useNavigation, useFetcher, or useRevalidator: follow step 4 (check consumer hooks). otherwise skip to step 5.
• if the file exports shouldRevalidate: follow step 5 (check shouldRevalidate). otherwise skip to step 6.
• if the component or loader calls defer(): follow step 6 (check defer and streaming). otherwise skip to step 7.
• if any potential issue is identified: run step 7 (hard gates). if any hard gate fails, do not report the issue. if all gates pass, proceed to step 8.
• if step 8 finds a matching valid pattern: do not flag the issue. otherwise continue to step 9.
• if step 9 requires context (e.g. "flag only if data is server-available"): check the specific context. if context does not apply, do not flag. if context applies, proceed to step 10.
• if the issue reaches step 10: write a finding with full location evidence and rule reference.

output contract

findings are structured as:

LOCATION: <repo-path-to-file>:<line-range-or-quote>
SEVERITY: [SECURITY | CORRECTNESS | ERGONOMICS]
RULE: [item from Review Checklist or Hard gates]
FINDING: <one-paragraph issue statement with concrete impact>
REFERENCE: [section from Valid Patterns or Context-Sensitive Rules or reference doc]

each finding must pass all hard gates (location evidence, exemption check, type-annotation check, v1 holdover check, protocol verification) before inclusion in the output. findings are ordered by severity. a successful review with no findings outputs:

RESULT: PASS
SCOPE: [file paths reviewed]

outcome signal

• skill executed successfully if you completed all 10 procedure steps and produced either: (a) a list of findings that each pass all five hard gates, or (b) a PASS result with scope listed.
• skill detected no issues if every potential issue is exempted by Valid Patterns (Do NOT Flag) or fails the Context-Sensitive Rules check, and you output a PASS result.
• skill failed to execute if you could not access the route module files, could not run the pre-review checklist, or attempted to report a finding that fails any hard gate. in this case, output a FAIL result with reason.

scope

• in scope: route modules under app/routes/ exporting loader, action, shouldRevalidate, or headers; components that consume useLoaderData, useActionData, useNavigation, useFetcher, useRevalidator, <Await>.
• out of scope: form ergonomics (<Form> markup, accessibility, useFetcher UI patterns) covered by remix-v2-forms-review. route module conventions, file naming, nested routing, error boundary placement covered by remix-v2-routing-review.
• imports expected: @remix-run/node (or @remix-run/cloudflare / @remix-run/deno) for server utilities; @remix-run/react for hooks and components.

quick reference

review checklist

• data needed for first render is in loader, not useEffect
• loaders only read; writes live in action
• request.formData() results are validated (zod/valibot/invariant) before use
• loader/action return values are projected DTOs , no password hashes, tokens, or internal_* fields
• useLoaderData<typeof loader>() uses the type annotation form (not as Foo)
• 404 / auth short-circuits throw a Response (or json/redirect), never a plain Error or string
• successful action returns redirect(...) (PRG); validation failures return json({ errors }, { status: 400 })
• action handles both success and error branches; no silent return null
• params.foo is checked with invariant / zod before use
• pending UI reads useNavigation() / fetcher.state , no useTransition
• formMethod comparisons use UPPERCASE ("POST", not "post")
• shouldRevalidate returns defaultShouldRevalidate by default; opt-outs are narrow and justified
• defer() is used only when at least one promise streams (no await before passing it)
• every <Await> is wrapped in <Suspense> and has an errorElement
• useRevalidator().revalidate() is reserved for focus/polling/SSE , not called immediately after a <Form> post or fetcher.submit (Remix already revalidates)

valid patterns (do not flag)

these are correct Remix v2 usage and must not be reported as issues:

• useEffect for client-only data , loaders run server-side; localStorage, window dimensions, IntersectionObserver, and browser-only APIs belong in useEffect.
• loader returning null , a loader may legitimately return null (e.g. optional resource not present); flag only if it should be a 404 throw.
• useLoaderData<typeof loader>() as type annotation , the <typeof loader> is a generic parameter feeding SerializeFrom<T>, not a as-style type assertion. do not flag it as "unsafe cast."
• bare new Response(body, init) returns , v2 routes may return any Response; json() is an ergonomic wrapper, not a requirement. non-JSON bodies (binary, text, streams) correctly skip json().
• return redirect(...) from an action , both return redirect(...) and throw redirect(...) are legal in actions; throwing is required only from non-action helpers when you want to exit the calling function.
• loader declared without the request arg , loaders may destructure only what they need ({ params }, { context }, or () with no args); the unused arg is not a bug.
• parent loader revalidated after an unrelated action , this is default Remix behavior, not a smell. flag only if shouldRevalidate exists and is wrong.
• action returning json({ errors }, { status: 400 }) , this is the canonical validation-error pattern (keeps the form route rendered with field errors). not the same as the "no redirect on success" anti-pattern.
• useRevalidator for focus / polling / cross-tab sync , these are the documented use cases; only flag manual revalidate() calls that immediately follow a <Form> post or fetcher.submit Remix would already revalidate.
• SerializeFrom-induced type changes , Date typed as string, Map typed as {} after deserialization is correct wire-format behavior, not a typing bug.

context-sensitive rules

only flag these issues when the specific context applies:

hard gates (before writing findings)

run these in order. do not draft user-facing findings until every gate passes for the batch you are about to report.

1. location evidence , pass: each issue lists the repo path to the route module and either a line range or a short verbatim quote from the file you read (not from memory or diff-only guesswork). loader/action issues without a path to the export async function loader|action are not reportable.

2. exemption check , pass: for each issue, you can state in one line why it is not covered by Valid Patterns (Do NOT Flag). in particular: confirm useEffect is not loading client-only data; confirm a bare Response return is not intentionally non-JSON; confirm a loader returning null is not a legitimate optional read.

3. type-annotation vs type-assertion check , pass: before flagging an "unsafe cast" on loader/action consumption, confirm the code uses as (assertion) not useLoaderData<typeof loader>() (annotation) and not useActionData<typeof action>() (annotation). the generic form is the documented safe path and must not be flagged.

4. v1 holdover check , pass: before flagging "missing pending state," grep the file for useTransition, transition.submission, fetcher.type, formMethod === "post" or formMethod==='post' (lowercase, any whitespace/quote variation), and LoaderArgs / ActionArgs. if present, the finding is a v1-holdover migration issue, not a missing-feature issue (label it accordingly).

5. protocol , pass: you completed the pre-report verification checklist in review-verification-protocol for this review.

when to load references

• reviewing a loader body, return shape, params, throws, or sensitive-field leaks: references/loaders.md
• reviewing an action body, FormData validation, success/error branches, or PRG redirect: references/actions.md
• reviewing useNavigation / useTransition migrations, shouldRevalidate, or useRevalidator use: references/revalidation.md
• reviewing defer(), <Await>, <Suspense>, or streaming decisions: references/defer-await.md

review questions

1. is data needed for first render fetched in a loader, or is it stuck in a useEffect that defeats SSR and revalidation?
2. does every loader return a projected DTO, or do raw ORM records (with password, token, internal_* fields) leak to the browser?
3. does every action validate request.formData() with a schema before touching the database?
4. does the success branch of each action redirect(...) so refresh / back behaves correctly (PRG)?
5. is the consumer code using useLoaderData<typeof loader>() (annotation) not useLoaderData() as Foo (assertion)?
6. do any v1 holdovers remain (useTransition, transition.submission, fetcher.type, lowercase formMethod, LoaderArgs / ActionArgs)?
7. does shouldRevalidate return a literal false, or does it reach for defaultShouldRevalidate and opt out narrowly?
8. is defer() used only when at least one promise is passed unresolved, and is every <Await> wrapped in <Suspense> with