feat(react-expert): add error code research mode with 7 agents

Author: rickhanlonii

.claude/skills/react-expert/SKILL.md

@@ -314,6 +314,306 @@ Replace spaces in topic with hyphens (e.g., "suspense boundaries" → "suspense-
 - Issue #<number>: <title> - <url>
 ```
 
+## Error Code Research Mode
+
+When invoked with `error` as the first argument, this skill switches to error-code research mode.
+
+### Invocation
+
+```
+/react-expert error 310
+/react-expert error 31
+```
+
+### Step 1: Setup React Repo
+
+Same as standard mode (see above).
+
+### Step 2: Look Up Error Message
+
+Fetch the error codes JSON:
+
+```bash
+curl -s https://raw.githubusercontent.com/facebook/react/main/scripts/error-codes/codes.json | python3 -c "import sys,json; codes=json.load(sys.stdin); print(codes.get('<CODE>', 'NOT FOUND'))"
+```
+
+Record the exact message template. Note the number of `%s` placeholders.
+
+### Step 3: Dispatch 7 Parallel Research Agents
+
+Spawn these agents IN PARALLEL using the Task tool. Each agent receives the skepticism preamble plus the error message template.
+
+| Agent | subagent_type | Focus |
+|-------|---------------|-------|
+| error-source-finder | Explore | Find all throw sites for this error code |
+| test-explorer | Explore | Find tests that trigger this error |
+| source-explorer | Explore | Find related warnings and dev-mode messages |
+| pr-researcher | Explore | Find PRs that introduced or modified this error |
+| issue-hunter | Explore | Find GitHub issues reporting this error |
+| web-researcher | general-purpose | Web search for real-world developer struggles |
+| git-historian | Explore | Find commits related to this error |
+
+### Step 4: Error-Specific Agent Prompts
+
+#### error-source-finder
+```
+You are researching React error code <CODE>.
+Error message: "<MESSAGE>"
+
+CRITICAL: Do NOT rely on your prior knowledge. Only report what you find in source files.
+
+Your task: Find every location in the React source that throws error code <CODE>.
+
+1. Search: grep -rn "<CODE>" .claude/react/packages/*/src/ (look for the error code in error/invariant calls)
+2. Also search: grep -rn "error(<CODE>" .claude/react/packages/*/src/
+3. For each throw site, document:
+   - The exact file path and line number
+   - The condition (if statement / validation) that triggers the throw
+   - What each %s argument resolves to at that call site
+   - The function/module context
+4. Determine which throw sites correspond to user-facing scenarios vs internal invariants
+
+Format:
+## Throw Sites
+### Site 1: <file>:<line>
+**Condition:** <the if/validation check>
+**Arguments:** %s1 = <value>, %s2 = <value>
+**Context:** <function name and what it does>
+**User-facing:** Yes/No
+```
+
+#### test-explorer (error mode)
+```
+You are researching React error code <CODE>.
+Error message: "<MESSAGE>"
+
+CRITICAL: Do NOT rely on your prior knowledge. Only report what you find in source files.
+
+Your task: Find test files in .claude/react that trigger or test error <CODE>.
+
+1. Search for the error code in test files: grep -rn "<CODE>" .claude/react/packages/*/src/__tests__/
+2. Search for the error message text in tests
+3. For each test, extract:
+   - The test description (describe/it blocks)
+   - The code that triggers the error
+   - How the test asserts the error is thrown
+4. Report findings with exact file paths and line numbers
+
+Format:
+## Test File: <path>
+### Test: "<test description>"
+```javascript
+<exact code from test>
+```
+**Triggers error by:** <what the test does to cause the error>
+```
+
+#### source-explorer (error mode)
+```
+You are researching React error code <CODE>.
+Error message: "<MESSAGE>"
+
+CRITICAL: Do NOT rely on your prior knowledge. Only report what you find in source files.
+
+Your task: Find related warnings and dev-mode messages for error <CODE>.
+
+1. Find the file(s) where error <CODE> is thrown
+2. Look for related console.error/console.warn calls near the throw sites
+3. Check if there's a different dev-mode message that provides more detail
+4. Document any related error codes thrown from the same functions
+
+Format:
+## Dev-Mode Messages
+| Message | Relationship to Error <CODE> | Source |
+|---------|------------------------------|--------|
+| "<message>" | <how it relates> | <file:line> |
+
+## Related Error Codes
+| Code | Message | Thrown From Same Location? |
+|------|---------|--------------------------|
+```
+
+#### web-researcher (error mode only)
+```
+You are researching React error code <CODE>.
+Error message: "<MESSAGE>"
+
+IMPORTANT: Web search IS allowed for error code research. Use WebSearch and WebFetch tools.
+
+Your task: Find how real developers encounter and struggle with this error.
+
+1. Search for:
+   - "react error <CODE>"
+   - "react minified error <CODE>"
+   - "Minified React error #<CODE>"
+   - The error message text itself
+2. Look at Stack Overflow, GitHub Discussions, Reddit r/reactjs, and blog posts
+3. For each relevant result, document:
+   - What the developer was trying to do
+   - What caused the error in their case
+   - What solution worked
+   - What they struggled with or found confusing
+4. Identify the most common real-world scenarios
+
+Format:
+## Real-World Occurrences
+### Source: <URL>
+**Scenario:** <what the developer was doing>
+**Cause:** <what triggered the error>
+**Solution:** <what fixed it>
+**Confusion:** <what they found confusing>
+
+## Summary of Common Patterns
+1. Most common cause: ...
+2. Second most common: ...
+3. What confuses people most: ...
+```
+
+#### pr-researcher (error mode)
+```
+You are researching React error code <CODE>.
+Error message: "<MESSAGE>"
+
+CRITICAL: Do NOT rely on your prior knowledge. Only report what you find in PRs.
+
+Your task: Find PRs related to error <CODE>.
+
+1. Run: gh pr list -R facebook/react --search "error <CODE>" --state all --limit 20 --json number,title,url
+2. Also search: gh pr list -R facebook/react --search "<key words from error message>" --state all --limit 20 --json number,title,url
+3. For promising PRs, read details: gh pr view <number> -R facebook/react
+4. Look for: when this error was introduced, why, any changes to its behavior
+
+Format:
+## Key PRs
+### PR #<number>: <title>
+**URL:** <url>
+**Summary:** <what it introduced/changed about this error>
+**Design Rationale:** <why this error exists>
+```
+
+#### issue-hunter (error mode)
+```
+You are researching React error code <CODE>.
+Error message: "<MESSAGE>"
+
+CRITICAL: Do NOT rely on your prior knowledge. Only report what you find in issues.
+
+Your task: Find GitHub issues where users report error <CODE>.
+
+1. Search: gh issue list -R facebook/react --search "error <CODE>" --state all --limit 20 --json number,title,url
+2. Search: gh issue list -R facebook/react --search "Minified React error #<CODE>" --state all --limit 20 --json number,title,url
+3. Search: gh issue list -R reactjs/react.dev --search "error <CODE>" --state all --limit 20 --json number,title,url
+4. For each issue, identify:
+   - What triggered the error
+   - The resolution
+   - Common misunderstandings
+
+Format:
+## Issues
+### Issue #<number>: <title>
+**Repo:** <repo>
+**Trigger:** <what caused the error>
+**Resolution:** <how it was resolved>
+**Misunderstanding:** <if applicable>
+```
+
+#### git-historian (error mode)
+```
+You are researching React error code <CODE>.
+Error message: "<MESSAGE>"
+
+CRITICAL: Do NOT rely on your prior knowledge. Only report what you find in git history.
+
+Your task: Find commits related to error <CODE>.
+
+1. Run: cd .claude/react && git log --all --grep="<CODE>" --oneline -30
+2. Also: cd .claude/react && git log --all --grep="<key words from message>" --oneline -30
+3. For significant commits, read full message: git show <hash> --stat
+4. Look for when this error was introduced, modified, or discussed
+
+Format:
+## Key Commits
+### <short hash> - <subject>
+**Date:** <date>
+**Context:** <why this change was made>
+**Impact:** <what changed about this error>
+```
+
+### Step 5: Synthesize Results
+
+After all agents complete, combine findings into a research document. Prioritize:
+1. Throw sites and their conditions
+2. Real-world causes (ordered by frequency from web research)
+3. Developer pain points and confusion
+4. Design rationale
+
+**DO NOT add information from your own knowledge.** Only include what agents found.
+
+### Step 6: Save Output
+
+Write to `.claude/research/error-<CODE>.md`
+
+### Error Research Output Template
+
+```markdown
+# React Error Research: Error #<CODE>
+
+> Generated by /react-expert error <CODE> on YYYY-MM-DD
+> Error message: "<message template>"
+> Sources: React repo (commit <hash>), N throw sites, M issues, K web results
+
+## Error Message
+
+<exact template>
+
+**Placeholders:** %s1 = <what it represents>, %s2 = ...
+
+## Throw Sites
+
+[From error-source-finder]
+
+## Common Real-World Causes
+
+[Synthesized from all agents — ordered by frequency from web research]
+
+1. **<cause>** — seen in N Stack Overflow posts, M GitHub issues
+2. **<cause>** — seen in ...
+
+## Developer Pain Points
+
+[From web-researcher — what confuses people]
+
+## Dev-Mode Messages
+
+[From source-explorer — messages shown in development that differ from production]
+
+## Test Coverage
+
+[From test-explorer — how React's own tests exercise this error]
+
+## Design Decisions
+
+[From git-historian and pr-researcher — why this error exists]
+
+## GitHub Issues
+
+[From issue-hunter]
+
+## Source Links
+
+### Commits
+- <hash>: <description>
+
+### Pull Requests
+- PR #<number>: <title> - <url>
+
+### Issues
+- Issue #<number>: <title> - <url>
+
+### Web Sources
+- <url>: <brief description>
+```
+
 ## Common Mistakes to Avoid
 
 1. **Trusting prior knowledge** - If you "know" something about the API, find the source evidence anyway