/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 res