write

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

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.