[claude] Add /write command

.claude/skills/write/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: write
+description: Use when creating new React documentation pages or updating existing ones. Accepts instructions like "add optimisticKey reference docs", "update ViewTransition with Activity", or "transition learn docs".
+---
+
+# Documentation Writer
+
+Orchestrates research, writing, and review for React documentation.
+
+## Invocation
+
+```
+/write add optimisticKey              → creates new reference docs
+/write update ViewTransition Activity → updates ViewTransition docs to cover Activity
+/write transition learn docs          → creates new learn docs for transitions
+/write blog post for React 20         → creates a new blog post
+```
+
+## Workflow
+
+```dot
+digraph write_flow {
+    rankdir=TB;
+    "Parse intent" [shape=box];
+    "Research (parallel)" [shape=box];
+    "Synthesize plan" [shape=box];
+    "Write docs" [shape=box];
+    "Review docs" [shape=box];
+    "Issues found?" [shape=diamond];
+    "Done" [shape=doublecircle];
+
+    "Parse intent" -> "Research (parallel)";
+    "Research (parallel)" -> "Synthesize plan";
+    "Synthesize plan" -> "Write docs";
+    "Write docs" -> "Review docs";
+    "Review docs" -> "Issues found?";
+    "Issues found?" -> "Write docs" [label="yes - fix"];
+    "Issues found?" -> "Done" [label="no"];
+}
+```
+
+### Step 1: Parse Intent
+
+Determine from the user's instruction:
+
+| Field | How to determine |
+|-------|------------------|
+| **Action** | "add"/"create"/"new" = new page; "update"/"edit"/"with" = modify existing |
+| **Topic** | The React API or concept (e.g., `optimisticKey`, `ViewTransition`, `transitions`) |
+| **Doc type** | "reference" (default for APIs/hooks/components), "learn" (for concepts/guides), "blog" (for announcements) |
+| **Target file** | For updates: find existing file in `src/content/`. For new: determine path from doc type |
+
+If the intent is ambiguous, ask the user to clarify before proceeding.
+
+### Step 2: Research (Parallel Agents)
+
+Spawn these agents **in parallel**:
+
+#### Agent 1: React Expert Research
+
+Use a Task agent (subagent_type: `general-purpose`) to invoke `/react-expert <topic>`. This researches the React source code, tests, PRs, issues, and type signatures.
+
+**Prompt:**
+```
+Invoke the /react-expert skill for <TOPIC>. Follow the skill's full workflow:
+setup the React repo, dispatch all 6 research agents in parallel, synthesize
+results, and save to .claude/research/<topic>.md. Return the full research document.
+```
+
+#### Agent 2: Existing Docs Audit
+
+Use a Task agent (subagent_type: `Explore`) to find and read existing documentation for the topic.
+
+**Prompt:**
+```
+Find all existing documentation related to <TOPIC> in this repo:
+1. Search src/content/ for files mentioning <TOPIC>
+2. Read any matching files fully
+3. For updates: identify what sections exist and what's missing
+4. For new pages: identify related pages to understand linking/cross-references
+5. Check src/sidebarLearn.json and src/sidebarReference.json for navigation placement
+
+Return: list of existing files with summaries, navigation structure, and gaps.
+```
+
+#### Agent 3: Use Case Research
+
+Use a Task agent (subagent_type: `general-purpose`) with web search to find common use cases and patterns.
+
+**Prompt:**
+```
+Search the web for common use cases and patterns for React's <TOPIC>.
+Focus on:
+1. Real-world usage patterns developers actually need
+2. Common mistakes or confusion points
+3. Migration patterns (if replacing an older API)
+4. Framework integration patterns (Next.js, Remix, etc.)
+
+Return a summary of the top 5-8 use cases with brief code sketches.
+Do NOT search Stack Overflow. Focus on official docs, GitHub discussions,
+and high-quality technical blogs.
+```
+
+### Step 3: Synthesize Writing Plan
+
+After all research agents complete, create a writing plan that includes:
+
+1. **Page type** (from docs-writer-reference decision tree or learn/blog type)
+2. **File path** for the new or updated file
+3. **Outline** with section headings matching the appropriate template
+4. **Content notes** for each section, drawn from research:
+   - API signature and parameters (from react-expert types)
+   - Usage examples (from react-expert tests + use case research)
+   - Caveats and pitfalls (from react-expert warnings/errors/issues)
+   - Cross-references to related pages (from docs audit)
+5. **Navigation changes** needed (sidebar JSON updates)
+
+Present this plan to the user and confirm before proceeding.
+
+### Step 4: Write Documentation
+
+Dispatch a Task agent (subagent_type: `general-purpose`) to write the documentation.
+
+**The agent prompt MUST include:**
+
+1. The full writing plan from Step 3
+2. An instruction to invoke the appropriate skill:
+   - `/docs-writer-reference` for reference pages
+   - `/docs-writer-learn` for learn pages
+   - `/docs-writer-blog` for blog posts
+3. An instruction to invoke `/docs-components` for MDX component patterns
+4. An instruction to invoke `/docs-sandpack` if adding interactive code examples
+5. The research document content (key findings, not the full dump)
+
+**Prompt template:**
+```
+You are writing React documentation. Follow these steps:
+
+1. Invoke /docs-writer-<TYPE> to load the page template and conventions
+2. Invoke /docs-components to load MDX component patterns
+3. Invoke /docs-sandpack if you need interactive code examples
+4. Write the documentation following the plan below
+
+PLAN:
+<writing plan from Step 3>
+
+RESEARCH FINDINGS:
+<key findings from Step 2 agents>
+
+Write the file to: <target file path>
+Also update <sidebar JSON> if adding a new page.
+```
+
+### Step 5: Review Documentation
+
+Invoke `/review-docs` on the written files. This dispatches parallel review agents checking:
+- Structure compliance (docs-writer-*)
+- Voice and style (docs-voice)
+- Component usage (docs-components)
+- Sandpack patterns (docs-sandpack)
+
+### Step 6: Fix Issues
+
+If the review finds issues:
+1. Present the review checklist to the user
+2. Fix the issues identified
+3. Re-run `/review-docs` on the fixed files
+4. Repeat until clean
+
+## Important Rules
+
+- **Always research before writing.** Never write docs from LLM knowledge alone.
+- **Always confirm the plan** with the user before writing.
+- **Always review** with `/review-docs` after writing.
+- **Match existing patterns.** Read neighboring docs to match style and depth.
+- **Update navigation.** New pages need sidebar entries.