feat: add error 321 page, update skill rules, and add error reviewer

Author: rickhanlonii

.claude/skills/docs-writer-error/SKILL.md

@@ -61,19 +61,31 @@ Place the file at `src/content/errors/{code}.md`. Use the template below.
 ```mdx
 <Intro>
 
-In the minified production build of React, we avoid sending down full error messages in order to reduce the number of bytes sent over the wire.
+This page explains this React error and common ways to fix it.
 
 </Intro>
 
-We highly recommend using the development build locally when debugging your app since it tracks additional debug info and provides helpful warnings about potential problems in your apps, but if you encounter an exception while using the production build, this page will reassemble the original error message.
-
-The full text of the error you just encountered is:
+The full text of the error is:
 
 <ErrorDecoder />
 
+<Note>
+
+In the minified production build of React, full error messages are replaced with short codes to reduce bundle size. We recommend using the development build when debugging, as it includes additional warnings and debug information.
+
+</Note>
+
 ## What This Error Means {/*what-this-error-means*/}
 
-[Plain-language explanation. 1-3 paragraphs.]
+[One-line opener ending with `:` — identifies the error condition]:
+
+` ` `js {N}
+[Minimal code showing the broken pattern, with // 🔴 marker and line highlight]
+` ` `
+
+[1-2 paragraphs explaining why this causes an error — what React was doing, what concept is involved.]
+
+[See the examples below for common causes and how to fix them.](#common-causes)
 
 ## Common Causes {/*common-causes*/}
 
@@ -103,6 +115,8 @@ Here is an example of code that would trigger this error:
 
 </Sandpack>
 
+[Optional: 1-2 sentences of supplementary context, e.g., related patterns or edge cases.]
+
 ## Related Documentation {/*related-documentation*/}
 
 - [Link text](/path/to/page)
@@ -112,32 +126,39 @@ Here is an example of code that would trigger this error:
 
 ### Boilerplate (Required, Verbatim)
 
-The `<Intro>` block, the paragraph about development builds, and `<ErrorDecoder />` must appear on every error page exactly as shown. Do not modify, reword, or omit any part.
+The `<Intro>` block, `<ErrorDecoder />`, and the `<Note>` about minified builds must appear on every custom error page exactly as shown in the template. Do not modify, reword, or omit any part. The intro leads with purpose ("explains this React error and common ways to fix it"), and the minification context is placed in a `<Note>` after the error decoder. The generic error page (`generic.md`) uses a different boilerplate — this skill only covers custom error pages.
 
 ### What This Error Means
 
-- Open with: "This error occurs when [condition]."
-- Explain what React was doing when it threw the error.
-- If the message has `%s` placeholders, explain what each represents.
-- Do not repeat the error message text — `<ErrorDecoder />` already shows it.
-- Name the specific React concept involved.
-- Address the developer pain points found in research — if people commonly misunderstand why this error happens, address that confusion directly.
+**Structure (in order):**
+1. Open with "This error occurs when [condition]:" — one sentence, ending with a colon, linking to relevant docs if applicable.
+2. Show a plain fenced code block (not Sandpack) with the broken pattern — use `{N}` line highlighting on the problematic line and a `// 🔴` comment marker.
+3. Explain why this causes an error in 1-2 paragraphs — what React was doing, what concept is involved. Address the developer pain points found in research — if people commonly misunderstand why this error happens, address that confusion directly.
+4. End with: `[See the examples below for common causes and how to fix them.](#common-causes)`
+
+**Rules:**
+- The code block is a quick illustrative snippet, NOT an interactive Sandpack — it gives the reader instant visual recognition of the broken pattern.
+- Use line highlighting (`{N}`) to point to the exact problematic line.
+- The `// 🔴` marker comment in the code block may reference the error concept (e.g., `// 🔴 Invalid Hook call!`).
+- If the message has `%s` placeholders, explain what each represents in the explanation paragraphs.
+- The explanation paragraphs follow the code — "show, then explain."
+- Keep the code block minimal (under ~15 lines) — just enough to show the pattern.
 
-**Opening sentence patterns:**
+**Opening sentence patterns** (all end with `:`):
 
 | Category | Pattern |
 |----------|---------|
-| Hooks | "This error occurs when a Hook is called in a way that violates the [Rules of Hooks](/reference/rules/rules-of-hooks)." |
-| Rendering | "This error occurs when React encounters [invalid element/children] during rendering." |
-| Hydration | "This error occurs when the HTML generated by the server does not match what the client renders." |
-| Server Components | "This error occurs when a value that is not serializable is passed from a Server Component to a Client Component." |
-| Suspense | "This error occurs when a component suspends during rendering without a `<Suspense>` boundary to catch it." |
+| Hooks | "This error occurs when a Hook is called in a way that violates the [Rules of Hooks](/reference/rules/rules-of-hooks):" |
+| Rendering | "This error occurs when React encounters [invalid element/children] during rendering:" |
+| Hydration | "This error occurs when the HTML generated by the server does not match what the client renders:" |
+| Server Components | "This error occurs when a value that is not serializable is passed from a Server Component to a Client Component:" |
+| Suspense | "This error occurs when a component suspends during rendering without a `<Suspense>` boundary to catch it:" |
 
 ### Common Causes
 
 - 1-4 causes per page. Most errors have 2-3.
 - Each cause gets its own `###` heading under `## Common Causes`.
-- Each cause must include: prose explanation, Problem Sandpack, Solution Sandpack.
+- Each cause must include: prose explanation, and either a Problem/Solution Sandpack pair, or plain code blocks. Build/configuration causes may use diagnostic commands and fix snippets instead.
 - Use descriptive headings: "Calling a Hook inside a condition", not "Cause 1".
 - **Order by real-world frequency**: Use web search and GitHub issue data from the research to determine which causes developers hit most often. The most common cause goes first.
 - **Address real confusion**: If the research shows developers struggle to understand why a particular pattern causes this error, explain it clearly in the prose.
@@ -156,6 +177,7 @@ For general Sandpack conventions, invoke `/docs-sandpack`.
 
 - Mark problematic code with `// 🔴`.
 - Keep examples minimal — only code needed to trigger the error.
+- When the error being documented also triggers a lint rule, include `// eslint-disable-next-line` to suppress the lint error so the Sandpack demonstrates the runtime behavior.
 - Must have `export default` in main file.
 - **Base examples on real-world patterns** found in web search results — not abstract/contrived scenarios.
 
@@ -255,7 +277,7 @@ Keep these pages minimal. Do not invent common causes.
 
 **Do:**
 - Invoke `/react-expert error <CODE>` before writing
-- Use the boilerplate verbatim
+- Use the boilerplate verbatim (intro, error decoder, minification note)
 - Explain what `%s` placeholders represent
 - Show problem code before solution (problem-first)
 - Keep Sandpack examples minimal
@@ -268,7 +290,7 @@ Keep these pages minimal. Do not invent common causes.
 **Don't:**
 - Write error pages without research
 - Add frontmatter to error pages
-- Modify the boilerplate text
+- Modify the boilerplate text (intro, error decoder, or minification note)
 - Repeat the error message in prose
 - Include more than 4 causes
 - Use contrived/abstract examples when real-world patterns exist
@@ -280,11 +302,11 @@ Keep these pages minimal. Do not invent common causes.
 ## Critical Rules
 
 1. **Research first:** Always invoke `/react-expert error <CODE>` before writing.
-2. **Boilerplate is sacred:** `<Intro>`, dev build paragraph, and `<ErrorDecoder />` must appear verbatim.
+2. **Boilerplate is sacred:** `<Intro>`, `<ErrorDecoder />`, and the minification `<Note>` must appear verbatim on every custom error page.
 3. **No frontmatter:** Error pages have no YAML frontmatter.
 4. **All headings require IDs:** `## Title {/*title-id*/}` in kebab-case.
 5. **Problem-first Sandpacks:** Show broken code before the fix.
-6. **One pair per cause:** Each cause gets one problem + one solution Sandpack (or plain code blocks).
+6. **One pair per cause:** Each cause gets one problem + one solution Sandpack (or plain code blocks). Exception: build/configuration causes (e.g., duplicate packages) may use diagnostic commands and fix snippets instead of a strict problem/solution pair.
 7. **Real-world examples:** Base Sandpack examples on patterns from web research, not contrived scenarios.
 8. **No consecutive callouts:** Separate `<Pitfall>`/`<Note>` with prose.
 9. **Minimal examples:** Keep Sandpack files under 50 lines when possible.

.claude/skills/review-docs/SKILL.md

@@ -9,6 +9,7 @@ Run these tasks in parallel for the given file(s). Each agent checks different a
 - [ ] Ask docs-reviewer agent to review {files} with docs-writer-learn (only for files in src/content/learn/).
 - [ ] Ask docs-reviewer agent to review {files} with docs-writer-reference (only for files in src/content/reference/).
 - [ ] Ask docs-reviewer agent to review {files} with docs-writer-blog (only for files in src/content/blog/).
+- [ ] Ask docs-reviewer agent to review {files} with docs-writer-error (only for files in src/content/errors/).
 - [ ] Ask docs-reviewer agent to review {files} with docs-voice (all documentation files).
 - [ ] Ask docs-reviewer agent to review {files} with docs-components (all documentation files).
 - [ ] Ask docs-reviewer agent to review {files} with docs-sandpack (files containing Sandpack examples).

src/content/errors/321.md

@@ -0,0 +1,127 @@
+<Intro>
+
+This page explains this React error and common ways to fix it.
+
+</Intro>
+
+The full text of the error is:
+
+<ErrorDecoder />
+
+<Note>
+
+In the minified production build of React, full error messages are replaced with short codes to reduce bundle size. We recommend using the development build when debugging, as it includes additional warnings and debug information.
+
+</Note>
+
+## What This Error Means {/*what-this-error-means*/}
+
+This error occurs when a Hook is called in a way that violates the [Rules of Hooks](/reference/rules/rules-of-hooks):
+
+```js {4}
+export default function Counter() {
+  function handleClick() {
+    // 🔴 Invalid Hook call!
+    const [count, setCount] = useState(0);
+    setCount(count + 1);
+  }
+
+  return <button onClick={handleClick}>Click me</button>;
+}
+```
+
+You can only call Hooks at the top level of a function component or a custom Hook. React tracks Hooks by associating them with the component that is currently rendering. When you call a Hook and no component is rendering, React cannot associate the Hook with a component, and throws this error.
+
+The most common cause is calling a Hook outside a function component. For example, inside an event handler, a class component, or a regular function. Another common cause is having **multiple copies of React** loaded in your app, which is a build configuration problem, not a coding mistake.
+
+[See the examples below for common causes and how to fix them.](#common-causes)
+
+## Common Causes {/*common-causes*/}
+
+### Calling a Hook outside the body of a function component {/*calling-a-hook-outside-the-body-of-a-function-component*/}
+
+React requires you to call Hooks at the top level of a function component or a custom Hook—not inside event handlers, nested functions, or class components.
+
+Here is an example of code that would trigger this error:
+
+<Sandpack>
+
+```js {expectedErrors: {'react-compiler': [7]}}
+import { useState } from 'react';
+
+export default function Counter() {
+  function handleClick() {
+    // 🔴 useState is called inside an event handler, not the component body
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    const [count, setCount] = useState(0);
+    setCount(count + 1);
+  }
+
+  return <button onClick={handleClick}>Click me</button>;
+}
+```
+
+</Sandpack>
+
+To fix this, move the Hook call to the top level of your component:
+
+<Sandpack>
+
+```js
+import { useState } from 'react';
+
+// ✅ Fixed: useState is called at the top level of the component
+export default function Counter() {
+  const [count, setCount] = useState(0);
+
+  function handleClick() {
+    setCount(count + 1);
+  }
+
+  return <button onClick={handleClick}>Count: {count}</button>;
+}
+```
+
+</Sandpack>
+
+The same rule applies to class components—you cannot use Hooks in class components. If you need state or other React features in a class component, [convert it to a function component](/reference/react/Component#alternatives).
+
+### Multiple copies of React in your app {/*multiple-copies-of-react*/}
+
+If your project uses a monorepo, `npm link`, or a third-party package that bundles its own copy of React, you can end up with two separate copies of React loaded at the same time. When this happens, the copy of React that your component uses is different from the copy that `react-dom` uses, and Hooks break because React can't track them across copies.
+
+To check if this is your problem, run the following from your project root:
+
+```bash
+npm ls react
+```
+
+If you see more than one entry for `react`, you have duplicate copies. You can also add a temporary log to confirm. Add this at the top of your component file:
+
+```js
+import React from 'react';
+console.log(React === window.React); // false means duplicates
+```
+
+If you're using webpack, you can fix this by adding a resolve alias in your webpack config:
+
+```js
+// webpack.config.js
+module.exports = {
+  resolve: {
+    alias: {
+      react: require.resolve('react'),
+      'react-dom': require.resolve('react-dom'),
+    },
+  },
+};
+```
+
+If you're using Vite, add a similar alias in your Vite config. For other bundlers, consult their documentation on how to configure module aliases.
+
+## Related Documentation {/*related-documentation*/}
+
+- [Rules of Hooks](/reference/rules/rules-of-hooks)
+- [`useState`](/reference/react/useState)
+- [Your First Component](/learn/your-first-component)
+- [Reusing Logic with Custom Hooks](/learn/reusing-logic-with-custom-hooks)