/research-write

Research Write Skill

Description

Orchestrates multi-agent collaborative writing from upstream research artifacts. Produces structured documents (papers, proposals) with evidence-grounded prose, MAGI cross-review, and automated quality validation.

Usage

/research-write --source <output_dir> [--mode paper|proposal] [--audience general-public|high-school|undergraduate|phd-student|researcher|expert|"free text"] [--depth low|medium|high] [--claude-only] [--resume <write_dir>]

Arguments

• `$ARGUMENTS` — Required and optional flags:
• `--source <output_dir>` — Path to an upstream research output directory containing artifacts from `/research`, `/research-brainstorm`, `/research-explain`, or `/research-report`. Required unless `--resume` is provided.
• `--mode` — Writing mode (default: `paper`):
• `paper` — Academic research paper with standard structure (abstract, introduction, methodology, experiments, results, discussion, limitations, conclusion, references)
• `proposal` — Grant or funding proposal with persuasive structure (executive summary, problem statement, proposed approach, preliminary results, timeline, budget, broader impact, references)
• `--audience` — Target audience (default: `researcher`):
• `general-public` — No assumed technical background
• `high-school` — Basic math/science literacy
• `undergraduate` — Introductory college-level knowledge in the domain
• `phd-student` — Graduate-level domain knowledge
• `researcher` — Active researcher familiar with the field (default)
• `expert` — Deep specialist in the exact sub-field
• `"free text"` — Any custom audience description (e.g., `"medical doctors learning ML"`)
• `--depth` — Controls review thoroughness (default: `medium`):
• `low` — Skip MAGI cross-review; Claude reviews alone
• `medium` — Standard MAGI cross-review (Gemini + Codex review in parallel)
• `high` — MAGI cross-review + Devil's Advocate adversarial pass on high-stakes sections
• `--claude-only` — Replace all Gemini/Codex MCP calls with Claude Agent subagents. Use when external model endpoints are unavailable. See **Claude-Only Mode** section below.
• `--resume <write_dir>` — Resume an interrupted write pipeline from a previous write output directory. See **Resume Protocol** below.

Instructions

> **Shared rules**: Read `${CLAUDE_PLUGIN_ROOT}/shared/rules.md` before starting. §MCP, §Claude-Only, §LaTeX, §Visualization, §Substitute apply to this skill. > **Inline fallback** (if shared rules unavailable): Gemini models: gemini-3.1-pro-preview → gemini-2.5-pro → Claude. Codex: gpt-5.4. All math in LaTeX only (no Unicode: σ₁→`$\sigma_1$`). Use `@filepath` for MCP file refs; subagents use `Read` tool.

MCP Tool Rules

See §MCP, §Visualization, §LaTeX in shared rules. Additionally:

• **Codex**: Use `mcp__codex-cli__ask-codex` for analysis/review.
• **When to search**: citation verification, related work references, fact-checking claims, confirming state-of-the-art results, checking terminology conventions

Claude-Only Mode

See §Claude-Only and §Substitute in shared rules.

LaTeX Formatting Rules

See §LaTeX in shared rules.

When this skill is invoked, follow these steps exactly:

---

Phase 0: Setup & Intake

Step 0a: Parse Arguments

1. Parse `$ARGUMENTS`:

• Extract `--source <output_dir>` (required unless `--resume`). Validate the directory exists using `Glob`.
• Extract `--mode` (default: `paper`). Validate against supported modes: `paper`, `proposal`.
• Extract `--audience` (default: `researcher`). Store as-is (predefined keyword or free-text string).
• Extract `--depth` (default: `medium`). Validate: `low`, `medium`, `high`.
• Extract `--claude-only` (boolean, default: `false`).
• **Parse `--resume <write_dir>`**: If provided, skip to the **Resume Protocol** below.

2. Determine the domain by reading upstream artifacts:

• Check for `brainstorm/weights.json` in the source directory — the `_meta.domain` field contains the domain.
• If not found, check `brainstorm/personas.md` for domain context.
• If neither exists, infer domain from the source directory name or contents.

3. Create the write output directory inside the source directory:

   {source_dir}/write/

If `write/` already exists, announce that existing artifacts will be preserved and new artifacts will be added alongside them.

4. Announce to the user: source directory, mode, audience, depth, domain, and claude-only status.

Step 0b: Locate Upstream Artifacts

Inventory the source directory for available artifacts using `Glob`:

| Artifact | Path | Required | Purpose | |:---------|:-----|:---------|:--------| | Brainstorm synthesis | `brainstorm/synthesis.md` | Recommended | Research directions, key findings | | Research plan | `plan/research_plan.md` | Recommended | Methodology, objectives | | Murder board | `plan/murder_board.md` | Optional | Stress-test results | | Mitigations | `plan/mitigations.md` | Optional | Plan revisions | | Source code | `src/**/*` | Optional | Implementation details | | Test results | `tests/**/*` | Optional | Validation data | | Plot manifest | `plots/plot_manifest.json` | Optional | Figures with metadata | | Report | `report.md` | Optional | Pre-existing report draft | | Explain outputs | `explain/**/*.md` | Optional | Concept explanations | | Brainstorm personas | `brainstorm/personas.md` | Optional | Expert persona context | | Weights | `brainstorm/weights.json` | Optional | Scoring weights used |

For each artifact found, read the first 5 lines to confirm it is non-empty.

**On missing recommended artifacts**: Warn the user which recommended artifacts are absent. Ask: "The following recommended artifacts are missing: [list]. The document will have thinner coverage in the corresponding sections. Proceed anyway?" Continue on confirmation.

Step 0c: Generate Intake Artifacts

Claude reads all located upstream artifacts and