write

# 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.