--- name: isolate-nextjs-hydration-and-rendering-regressions description: 'Diagnose Next.js hydration mismatches and server/client rendering failures by tracing observable symptoms to route, component, data, environment, and browser-only boundaries, then define the smallest safe repair and verification evidence. Use when a Next.js page shows hydration mismatch warnings, inconsistent server and client output, or route-specific rendering failures. A React component behaves differently after server render, client hydration, navigation, or deployment. A browser-only dependency, time/randomness, feature flag, user-specific data, or environment variable may be causing server-client divergence. A team needs a minimal, reviewable fix plan and test coverage before changing production rendering behavior.' compatibility: 'Instruction-only Agent Skill. Requires an Agent Skills-compatible client and access to the tools or systems named in the instructions. No executable scripts are bundled.' metadata: publisher: RichlyAI product: Amo.ng amo_id: AMO-S-000030 canonical_url: 'https://amo.ng/skills/isolate-nextjs-hydration-and-rendering-regressions' package_version: 1.0.0 source_type: prompt source_amo_id: AMO-P-000231 source_content_sha256: 8f73fb5a85627159ad758e80e9591700be014ca30a7acc8f4c97259539a67541 source_version: 1.0.0 --- # Isolate Next.js Hydration and Rendering Regressions ## When to use this Skill - A Next.js page shows hydration mismatch warnings, inconsistent server and client output, or route-specific rendering failures. - A React component behaves differently after server render, client hydration, navigation, or deployment. - A browser-only dependency, time/randomness, feature flag, user-specific data, or environment variable may be causing server-client divergence. - A team needs a minimal, reviewable fix plan and test coverage before changing production rendering behavior. ## When not to use this Skill - Do not use for general frontend styling or layout critique without a rendering or hydration defect. - Do not use when the application is not based on Next.js or a comparable React server/client rendering architecture. - Do not use to authorize deployment, merge code, or bypass normal code review and CI gates. - Do not use when no logs, route examples, screenshots, reproduction steps, or code context can be supplied; first gather evidence. ## Required inputs - Exact Next.js and React versions, routing model such as App Router or Pages Router, runtime, rendering mode, and relevant deployment adapter if known. - Affected route URLs or route names and the environments where the issue appears. - Hydration warnings, browser console output, server logs, CI output, screenshots, or user-visible symptoms. - Relevant components, layouts, data-fetching code, dynamic imports, middleware, feature flags, and environment configuration. - Expected behavior, actual behavior, reproduction steps, and any recent changes or deployments. - Available test commands, build commands, lint commands, and existing rendering or end-to-end tests. Use [INPUT-TEMPLATE.md](assets/INPUT-TEMPLATE.md) to organize the supplied information. ## Required tools or access Published source tool designations: Codex. These are source designations, not portable-client compatibility claims. Use only authorized access described in the inputs and source instructions. Do not claim access or inspection without evidence. ## Procedure Before starting, read [SOURCE.md](references/SOURCE.md), including the exact Prompt instructions and any ordered Workflow steps, review notes and carry-forward requirements. 1. Use the linked source prompt AMO-P-000231 as the investigation scaffold for a Next.js rendering failure; provide the required inputs in its context sections rather than copying the prompt into the final deliverable. 2. Separate supplied facts, observed evidence, assumptions, inferred causes, missing information, and uncertainty. 3. Map each symptom to the route, component boundary, rendering phase, data source, and environment where it is observed. 4. Preserve the server/client diagnostic boundary: compare supplied server-rendered and client-rendered evidence separately, then identify supported divergence sources such as browser-only APIs, nondeterministic values, cookies/session state, async data timing, locale/timezone differences, dynamic imports, or invalid HTML structure. 5. Rank root-cause hypotheses by direct evidence, reproducibility, blast radius, and ability to discriminate with a targeted check. 6. Propose the smallest behavior-preserving repair boundary and describe why broader rewrites are unnecessary unless evidence supports them. 7. Define verification checks: local reproduction, build, lint/type checks, route-level regression tests, browser checks, and any environment-specific validation needed. 8. Flag any production, deployment, data, privacy, or customer-impacting decisions for human review before action. Published expected output: A concise investigation brief containing the observed rendering failure, evidence map, ranked root-cause hypotheses, minimal repair plan, regression test plan, unresolved questions, risk notes, and human review or release gates. ## Review gates Read and apply the source review instructions in [SOURCE.md](references/SOURCE.md) before acting. Keep proposed, unrun and executed actions distinct; preserve missing evidence and obtain the human approvals required by the source. ## Completion criteria Complete when: - Every confirmed finding cites supplied logs, code locations, screenshots, reproduction steps, or test evidence. - The diagnosis distinguishes confirmed causes from plausible but unverified hypotheses. - The proposed fix targets a specific server/client divergence or rendering boundary. - Regression checks cover at least the affected route, a representative unaffected route if available, and the relevant build or runtime environment. - Open questions are explicit where evidence is missing. Use the [completion checklist](references/COMPLETION-CHECKLIST.md) and record unresolved items. ## Limitations - Do not claim that code was changed, a build or test ran, browser behaviour was observed, or a deployment occurred unless the user supplies evidence of that exact action and result. - Do not invent Next.js version details, logs, route behavior, or test results. - Keep proposed changes scoped to the responsible rendering boundary unless evidence justifies broader refactoring. - Preserve existing route contracts, accessibility, data privacy, analytics behavior, and user-visible behavior outside the defect. - Require human approval before merge, deployment, rollback, or production configuration changes. This is an instruction-only package. Packaging does not execute work, grant access or independently verify the package. Existing public verification in amo.json describes only the identified published source resources. ## References - [Published source instructions](references/SOURCE.md) - [Completion checklist](references/COMPLETION-CHECKLIST.md) - [Input template](assets/INPUT-TEMPLATE.md) - [Rights](RIGHTS.md) - [Canonical Amo.ng Skill](https://amo.ng/skills/isolate-nextjs-hydration-and-rendering-regressions)