docs: add guide for optimizing the static shell (#97737)
## What? Adds an **Optimizing the static shell** guide that follows one team settings route through focused Suspense boundaries, deferred authentication, cache-versus-stream decisions, loading-state reuse, shared layouts, and parallel routes. Updates `next-cache-components-optimizer` to use that guide and the canonical Insight pages as its framework source of truth. The original phase-based Skill workflow is preserved, including the production rig, exact test contract, trustworthy RED-to-GREEN loop, parity check, differential, and reporting. Reusable implementation guidance now links to the corresponding guide section instead of being duplicated in Skill-only references. Clarifies that the optimizer can target either a direct page load or a named client navigation. Both use the same App Shell patterns and `instant()` verification loop. When the destination App Shell is already instant and the goal is to include additional URL-specific content before a click, the Skill hands off to the Partial Prefetching optimizer. Aligns the Cache Components and Partial Prefetching optimizers around the same workflow: define the contract, reuse the production rig, prove current behavior, make the smallest optimization, verify and ship. Their framework-specific decisions remain separate. The Partial Prefetching adoption rig also receives the shared visible, committed DOM-marker rule because it uses the same `instant()` testing API. ## Why? The optimizer's framework patterns are useful outside the agent workflow. Keeping them in public docs gives developers and agents one source of truth while each Skill stays focused on its product decision and reliable production verification. ## Eval The corrected-contract comparison uses Claude Opus 4.8 and Claude Sonnet 4.5 with a fixed Claude Haiku 4.5 judge. It compares the baseline, bundled guide, production Skill from `canary`, and proposed local Skill. The bundled-guide and Skill treatments use a local Next.js tarball containing the new guide. The eval now contains 11 granular checks so product behavior, test quality, and workflow discipline are visible independently. They cover configuration, direct and client-navigation `instant()` coverage, exact shell markers, preserved data sources, reusable and request-time UI placement, all completed-route variants, viewer-cookie behavior, trustworthy RED, full-suite GREEN, and the bounded differential. The prompt names the Aurora, Nebula, unknown-release, and viewer-cookie parity cases explicitly. All eight treatments were rerun against this 11-check rubric. | Model | Treatment | Checks passed | Overall | Duration | Tokens processed | Total run cost | Cost change | | --- | --- | ---: | ---: | ---: | ---: | ---: | ---: | | Opus 4.8 | Baseline | 9/11 | Fail | 26m 38s | 4.83M | $4.66 | — | | Opus 4.8 | Bundled guide | 8/11 | Fail | 36m 36s | 4.99M | $5.29 | +13.5% | | Opus 4.8 | Production Skill | 9/11 | Fail | 28m 20s | 3.25M | $3.35 | -28.0% | | Opus 4.8 | Proposed Skill | **11/11** | **Pass** | 32m 9s | 5.25M | $5.24 | +12.5% | | Sonnet 4.5 | Baseline | 8/11 | Fail | 22m 31s | 2.73M | $1.29 | — | | Sonnet 4.5 | Bundled guide | 8/11 | Fail | 17m 58s | 2.38M | $1.18 | -8.1% | | Sonnet 4.5 | Production Skill | 4/11 | Fail | 27m 18s | 2.94M | $1.38 | +7.3% | | Sonnet 4.5 | Proposed Skill | 4/11 | Fail | 25m 26s | 5.49M | $2.53 | +96.1% | Token totals count each unique model message once and include uncached input, cache creation, cache reads, and output. Total run cost applies the current AI Gateway base rates to each token category. Judge cost is excluded. The eight runs processed 31.87M tokens and cost $24.91 in total, excluding the judge. This is one run per model and treatment, so the comparison is descriptive rather than a stable pass-rate measurement. The proposed Opus Skill is the only treatment to pass every check. Baseline and production Skill each passed 9/11, but both skipped the bounded differential. Baseline also missed the viewer-cookie timing lock. Production Skill omitted exact loading-state coverage. The guide-only treatment implemented the product behavior but missed an exact selector, trustworthy RED, and the differential. The proposed Sonnet Skill preserved the exact `instant()` contract, but replaced the existing runtime file read with a build-time import. It then stopped using the documented production command, encountered port conflicts from starting another Playwright server lifecycle, and never completed parity, GREEN, or a valid differential. This is a model adherence failure rather than a sandbox or credential failure. It shows that the restored workflow is sufficient for Opus but still too easy for Sonnet to abandon after it encounters test friction. ## Verification - Local Next.js build passed. - Prettier, TypeScript, ESLint through the commit hook, Alex, and diff checks passed. - Documentation link validation passed in CI. - All eight treatments finalized against the current 11-check rubric.
Showing
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
Please
register
or
sign in
to comment