magi-researchers

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

1. Determine the domain by reading upstream artifacts:
2. Check for brainstorm/weights.json in the source directory — the _meta.domain field contains the domain.
3. If not found, check brainstorm/personas.md for domain context.
4. If neither exists, infer domain from the source directory name or contents.

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

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