/next-partial-prefetching-optimizer

name: next-partial-prefetching-optimizer
description: >
  Optimize what selected Next.js client navigations include before the click
  under Partial Prefetching. Use after Cache Components and Partial Prefetching
  are adopted when the user wants selected URL-specific UI to be instant,
  wants reusable content to wait for navigation, or needs to choose between
  default, viewport, and intent prefetching. Requires Next.js 16.3+.

Partial Prefetching optimizer

Optimize each requested source link and destination as its own contract. Turn the requested prefetched UI, navigation-only UI, and trigger into a production [`instant()`](https://nextjs.org/docs/app/guides/instant-navigation#prevent-regressions-with-e2e-tests) test. Record the current behavior, make the smallest optimization, verify the differential, and keep the passing test as regression coverage.

Before making framework changes, read the bundled Optimizing prefetching guide at `node_modules/next/dist/docs/01-app/02-guides/optimizing-prefetching.md`. If the bundled guide is unavailable, use the [online guide](https://nextjs.org/docs/app/guides/optimizing-prefetching). It is the source of truth for prefetch stages, `prefetch={true}`, session-specific UI, and cost trade-offs.

When the work changes what belongs in the App Shell, follow the [Instant navigation](https://nextjs.org/docs/app/guides/instant-navigation) and [Caching](https://nextjs.org/docs/app/getting-started/caching) docs for cache placement, Suspense boundaries, loading UI, and authorization.

The guides own framework behavior and implementation patterns. This skill owns the navigation contract, production rig, trustworthy RED-to-GREEN loop, parity check, differential, and report.

This is not an adoption skill. If Cache Components or Partial Prefetching are not adopted, use their adoption skills and return to this workflow. If the App Shell itself cannot commit under `instant()`, use `next-cache-components-optimizer` first, then resume the selected navigation.

Run the workflow unattended. Resolve the contract from the request and the existing application. Stop for user input only when a product decision is genuinely blocked and cannot be inferred safely without changing cost, freshness, authorization, or user-visible behavior.

Reporting to the user

This loop runs unattended, so do not stop between implementation steps. Finish the navigations the user named, then check in. The rig, lock, RED/GREEN loop, and stage names are internal scaffolding; report the product behavior instead.

• **Speak their language.** Describe the source link and result in terms of

what the user sees before and after the click, not the validation mechanics.

• **Show, don't tell.** Drive the exact link in a production browser so the user

sees which content is already available and which content streams after the click. If a live demonstration is unavailable, attach before/after captures.

• **Give them a concise click-through list, not a technical results table.** Use

one line per navigation with the source URL, link to click, UI ready before the click, UI that waits for navigation, and whether prefetching starts in the viewport or after intent.

• **Only surface a question for a genuine fork.** Ask when the choice changes

cost, freshness, authorization, or visible behavior. If the user already requested a PR or named every navigation, finish that scope without asking again.

Define the contract

Inspect the source route, the exact link or interaction, the destination's Suspense boundaries, its data reads, existing prefetch policy, and any existing `instant()` test. Record:

• which destination UI should be ready before the click;
• which reusable UI should wait for navigation;
• whether per-link prefetching should start in the viewport or only after

intent.

The trigger is part of the contract. Two links to the same URL may use different prefetch policies and need separate tests.

Use the guide's cost model when the trigger is not already specified. Do not silently increase the number of links that can invoke the server or cache data whose freshness contract is unknown.

Reuse the production rig

Read an existing `instant-nav.rig.md`. Cache Components optimization, Partial Prefetching adoption, and this optimizer share the same build, auth, data, and Playwright contract. Add the exact source link, destination markers, and prefetch budget instead of creating another rig.

If the project has no rig, use [`rig-template.md`](rig-template.md) to discover and record one. The measured run must be a production build or preview where `experimental.exposeTestingApiInProductionBuild` is enabled only for testing. Development can help diagnose a route, but automatic link prefetching is production-only.

Prove the current behavior

Search for an existing `instant()` test for the exact source link and destination. Extend it when it already covers the same behavior. Otherwise, add a focused click-driven test using the guide's [prefetched and deferred content testing](https://nextjs.org/docs/app/guides/optimizing-prefetching#test-prefetched-and-deferred-content) pattern.

Keep one production browser test per source-link, destination, and trigger contract. Do not loop over several destinations or collect their readiness results in one test. Focused tests can still run serially in one browser worker.

First, run an unlocked scaffold that proves the link reaches the exact pathname and query and that the selected UI eventually renders for the test user. Do not ship this scaffold.

Then run the same interaction inside `instant()`. The existing App Shell must stay visible, while the guide's positive and negative assertions capture the prefetched result. After the lock releases, every selected region must eventually render.

Read [`reference/red-test-robustness.md`](reference/red-test-robustness.md) before treating this failure as RED. A timeout before the URL changes, a mis