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:

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 generates two structured JSON files. This is an LLM extraction task — Claude performs the semantic extraction; Python validates the schema.

Schema reference: Read references/intake_schemas.md for the full write_inputs.json and citation_ledger.json schemas and extraction guidelines.

1. Generate write/write_inputs.json using the schema in references/intake_schemas.md.

2. Generate write/citation_ledger.json using the schema in references/intake_schemas.md.

3. Validate with maintained utility:

Determine the plugin root directory by navigating two levels up from this skill's base directory (e.g., if this skill is loaded from .../skills/research-write/, the plugin root is ../../ relative to that path). The Base directory for this skill: header injected by Claude Code provides the absolute path. Then run:

uv run python <plugin_root>/utils/validate_intake.py write/write_inputs.json write/citation_ledger.json

Important: Do NOT generate a validation script at runtime. Use the maintained utils/validate_intake.py utility.

If validation fails, Claude fixes the JSON files and re-runs validation. Maximum 2 fix attempts.

Phase 1: Outline

Step 1a: Load Mode Template

Read the mode template from ${CLAUDE_PLUGIN_ROOT}/templates/writing/{mode}.md.

Parse the YAML frontmatter to extract:

• sections — ordered list of section definitions with id, required, max_words, evidence_slots, style, narrative_role
• export — target export formats
• total_max_words — overall word budget
• tone, jargon_budget, formality — style constraints

Read the Markdown body for section dependencies and evidence integration guidelines.

Save a copy of the loaded template to write/mode_template_cache.md before proceeding to Step 1b. This cached copy is referenced by @filepath in subsequent model calls.

Step 1b: MAGI Parallel Outline Generation

Full prompts: Read `references/outline_prom