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:

• Page type (from docs-writer-reference decision tree or learn/blog type)

• File path for the new or updated file

• Outline with section headings matching the appropriate template

• 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)

• 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:

• The full writing plan from Step 3

• 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

• An instruction to invoke /docs-components for MDX component patterns

• An instruction to invoke /docs-sandpack if adding interactive code examples

• 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:

• Present the review checklist to the user

• Fix the issues identified

• Re-run /review-docs on the fixed files

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