• Invariant: the verification loop. Maximizing the shell is worthless unless you can prove it. The proof is an automated check: under a lock that gates dynamic data, the static shell still commits. RED shows the gap, GREEN shows it closed, the test ships as the regression guard. It must run on a production-like build and must not be able to pass vacuously. Stand the loop up once; every later optimization is then verifiable by construction. The loop is the deliverable, not any one route.
• The mechanism:

  @next/playwright

  instant()

  . This skill uses

  instant()

  as a ruler, not a stopwatch (phase A). It comes from

  @next/playwright

  (installed alongside

  @playwright/test

  , on the same release line as

  next

  ), so it isn't tied to any host. Keep it. Timing a navigation by hand is too flaky to trust, and is the failure mode this skill exists to prevent.
• Yours: the rig. How you build, deploy, authenticate, configure Playwright, and loop belongs to your stack, not to this skill. A local

  next build && next start

  , a CI/staging container, and a per-push preview deploy are equally valid rigs; the verdict comes from the build, never the platform. Phase 0 maps the invariant onto your repo. Read every platform name, env-var spelling, and command below as an example to translate, not a requirement.

• Initial load (hard navigation) commits the route's prerendered static shell; deferred parts stream in behind their loading skeletons (Suspense fallbacks,

  loading.tsx

  ).
• Client-side navigation (soft navigation) commits the destination's prefetched App Shell — the

  <Link>

  default under Partial Prefetching — re-rendering only the segments that change.

reference/real-app-patterns.md

• Speak their language. Describe the gap and the result in terms of what the user sees: "navigating to the dashboard waited on the charts query before anything painted; now the layout and skeletons paint instantly and the charts stream in" — not RED/GREEN, the lock, or the phase letters.
• Show, don't tell. When you report a route, drive the browser (or attach before/after screenshots) so the user watches the shell commit immediately and the data stream in, rather than reading a claim. Identical before and after means the fix did nothing — roll it back.
• Present a run as a list of results the user can click through — one line per navigation: the route, what commits instantly, and what streams in — not a transcript of the loop.
• Only surface a question for a genuine fork: a fix that would change behavior, a security-sensitive read, or a route that's dynamic by design (a per-link-prefetch candidate, not a shell to grow). A clean instant fix is not a fork — keep going. With no one to ask (an unattended run), don't block: take the safe default and note the assumption — for a cache-freshness choice, defer the read behind

  <Suspense>

  (always fresh, still instant) rather than guess a

  cacheLife

  .

• Next.js 16.3+ with

  cacheComponents: true

  in

  next.config.ts

  . Without Cache Components there is no static shell to optimize.

• @next/playwright

  on the same release line as the project's

  next

  ; it provides

  instant()

  . Verify with

  npm ls next @next/playwright

  (or the project's package manager) and align them if they differ. The matching testing API is in the

  next

  runtime, gated by the

  experimental.exposeTestingApiInProductionBuild

  config flag (phase A).

npx @next/codemod upgrade

next.config.ts

export default { cacheComponents: true }

next-cache-components-adoption

instant-nav.rig.md

1. Never measure on

   next dev

   . It does not prefetch, and its lock is unreliable for blocking routes, so a dev

   instant()

   result is not a valid RED or GREEN.
2. The measured build must expose the testing API. Otherwise

   instant()

   silently no-ops and the test passes vacuously (see

   reference/red-test-robustness.md

   ). The lock-engagement proof is the phase-C RED itself: the unfixed target route is the known-blocking route, and its RED under the lock shows the lock engages on this build (C-gate); the self-validating variant in

   test-template.md

   is the in-band guarantee. Wire

   experimental.exposeTestingApiInProductionBuild

   to a condition that is true for every build you measure and never true in production:
   ts

   experimental: {
     // Use the condition your platform provides, and record it in the rig file:
     //   local:       an explicit opt-in, as below
     //   generic CI:  process.env.DEPLOY_ENV === 'staging'
     //   Vercel:      process.env.VERCEL_ENV === 'preview'
     exposeTestingApiInProductionBuild:
       process.env.EXPOSE_TESTING_API === '1',
   }

next build && next start

rig-template.md

HEAD

next build && next start

rig-template.md

instant()

test-template.md

reference/red-test-robustness.md

C-gate: do not start optimizing until the RED is verified trustworthy. A RED that is red for the wrong reason sends you optimizing a route that was never broken.

SHELL_MARKER

reference/red-test-robustness.md

<Suspense>

• The layout UI stays out of the static shell: only a throwaway copy of it is prerendered.
• The entire subtree is replaced when the boundary resolves, which discards client state and shifts layout.
• The hand-built fallback drifts out of sync as the UI changes, because it duplicates structure that also exists in the resolved tree.

children

await

<Suspense fallback={null}>

reference/real-app-patterns.md

await

await params

<Suspense>

fallback={null}

cookies()

headers()

searchParams

Date.now()

Math.random()

crypto.randomUUID()

https://nextjs.org/docs/messages/<slug>

--debug-prerender

next build --debug-build-paths "app/<route>/**"

reference/patterns.md

• A boundary in the root layout isn't enough for client navigations. It passes a page-load check but leaves sibling client navigations blocking; put the boundary below the lowest layout the source and destination routes share.
• Keep the LCP element (usually the main heading) out of any boundary, so it paints in the shell instead of waiting on a stream.
• A green check isn't always instant.

  export const instant = false

  opts the segment out of validation while the navigation still blocks, and a

  <Suspense>

  above the document

  <body>

  prerenders an empty shell — neither makes the route instant.

1. the route's

   loading.tsx

   ;
2. an exported

   *Skeleton

   colocated with the component;
3. the fallback already inside the component's own

   <Suspense>

   .

loading.tsx

loading.tsx

loading.tsx

null

fallback={null}

await page.setViewportSize({ width: 1280, height: 800 })

{ width: 390, height: 844 }

reference/real-app-patterns.md

D-gate: phase D is complete when the locked test from phase C passes GREEN under the lock on the production-build rig, not when the code compiles. That GREEN is the deterministic stop for the fix loop; proceed to E.

params

searchParams

<Link prefetch={true}>

reference/patterns.md

instant()

• Same render output. The moved

  await

  s compute and return the same values; after the stream, the route shows the same content as the base branch for the test user.
• Side effects still fire. A deferred

  redirect()

  or

  notFound()

  still happens, at request time rather than during prerender. Confirm an unauthorized user is still redirected and a missing record still returns 404.
• Both viewports reach the real UI after the stream (D2).
• Client state survives. Because the layout UI is hoisted into the stable shell rather than swapped on resolve, open menus, scroll position, focus, and input state persist across the stream.
• Pre-existing failures stay separate. If the route errors after the change, reproduce it on the base branch. The same failure there is an environment or data problem, not an optimizer regression.

reference/red-test-robustness.md

• Differential shown: RED without the fix, GREEN with it, runs linked.
• Parity confirmed (E): same content, redirects, and state.
• Existing loading UI reused (D1): no new page-mirroring skeleton.
• Shell matches the real render at desktop and mobile widths (D2).
• Baseline removed: only the locked test from C remains.

• Soft navigation → drive a real

  <Link>

  click. Initial load → use

  page.goto()

  inside

  instant()

  with the

  baseURL

  option. Do not substitute

  goto

  for a soft-nav verdict; the two shells can differ (

  test-template.md

  ,

  reference/real-app-patterns.md

  ).
• With parallel routes, only the slots that change re-render on a soft navigation; client-rendered navigation UI does not re-render at all. Do not chase a slot the navigation never touches (

  reference/real-app-patterns.md

  ).

• rig-template.md

  : phase 0, the six-question rig discovery, the

  instant-nav.rig.md

  template, and filled examples (local-only, generic CI, preview deploy).

• test-template.md

  : the shipped

  instant()

  specs for both navigation types (phase C), and the delete-before-PR baseline scaffold (phase B).

• reference/red-test-robustness.md

  : the C-gate and phase F. The taxonomy of untrustworthy REDs, the checklist, the differential recipe, the vacuous-pass failure mode, and worked cases.

• reference/real-app-patterns.md

  : parallel routes, deferring an auth gate, initial-load vs soft-navigation shells, the empty-shell failure mode, the responsive-skeleton mismatch, edge cases.

partialPrefetching: true

prefetch = 'partial'

rg -n "partialPrefetching|prefetch\s*=\s*['\"]partial['\"]" --glob 'next.config.*' --glob 'app/**' --glob 'src/app/**'

partialPrefetching: true

prefetch = 'partial'

• Already adopted: for any URL-data route that stopped at the limitation above, consider a targeted

  <Link prefetch={true}>

  on the links where having that URL-specific content ready before the click is worth the per-link server work. Keep the default link behavior everywhere else so the shared App Shell remains the low-cost baseline.
• Not adopted yet: recommend

  next-partial-prefetching-adoption

  . That skill moves the app onto the better prefetching model: shared App Shell prefetches by default, fewer duplicated full-prefetch requests for visible links, a link audit for existing

  <Link prefetch={true}>

  usage, and optional per-link prefetching only where URL-specific content is worth the extra server work.