/research

Research Workflow — Full Pipeline

Description

Runs the complete research pipeline: Brainstorming → Planning → Implementation → Testing & Visualization → Reporting. Orchestrates all phases with user checkpoints between each.

Usage

/research "research topic" [--domain physics|ai_ml|statistics|mathematics|paper] [--weights '{"novelty":0.4,...}'|adaptive] [--depth low|medium|high|max] [--personas N] [--claude-only] [--substitute "Gemini -> Opus"] [--resume <output_dir>]

Arguments

• `$ARGUMENTS` — The research topic (required) and optional flags:
• `--domain` — Research domain (physics, ai_ml, statistics, mathematics, paper). Auto-inferred if omitted.
• `--weights` — Scoring mode for direction ranking:
• **Omitted (default)**: Holistic ranking — Claude ranks directions by expert judgment with detailed rationale. No numeric weights.
• **JSON object**: Weighted scoring with dimension weights summing to 1.0.
• **`adaptive`**: Claude analyzes the prompt and recommends weights for user confirmation.

See `/research-brainstorm` for full details.

• `--depth` — Controls brainstorm review depth (default: `medium`):
• `low` — Skip cross-review, go directly to synthesis (fastest, lowest cost)
• `medium` — Standard one-shot cross-review (default)
• `high` — Cross-review + adversarial debate (most thorough, highest cost)
• `max` — Hierarchical MAGI-in-MAGI: N persona subagents run parallel mini-MAGI pipelines, then meta-review + adversarial debate across all perspectives (deepest, highest cost)
• `--personas N|auto` — Number of domain-specialist subagents for `--depth max` (default: `auto`, range: 2-4). When `auto`, Claude analyzes the topic to determine the optimal persona count. Ignored for other depth levels.
• `--claude-only` — Replace all Gemini/Codex MCP calls with Claude Agent subagents across all phases. Use when external model endpoints are unavailable. Forwarded to all sub-skills automatically.
• `--substitute "Agent -> Opus"` — Replace a specific MAGI agent with Claude (Opus). Accepted: `"Gemini -> Opus"`, `"Codex -> Opus"`. Can be specified multiple times. Forwarded to all sub-skills. If both agents are substituted, equivalent to `--claude-only`. Mutually exclusive with `--claude-only` (`--claude-only` takes precedence).
• `--resume <output_dir>` — Resume an interrupted pipeline from a previous output directory. See **Resume Protocol** below.

Instructions

> **Shared rules**: Read `${CLAUDE_PLUGIN_ROOT}/shared/rules.md` before starting. §MCP, §Visualization, §LaTeX, §PhaseGate, §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). scienceplots `['science','nature']`, 300dpi PNG+PDF, Nature widths (3.5/7.2in). 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__brainstorm` for ideation, `mcp__codex-cli__ask-codex` for analysis/review.
• **Context7**: Use during implementation phase for library documentation lookups.
• **When to search**: prior work verification, methodological precedents, dataset/library availability, related approaches, fact-checking quantitative claims

Path Safety Rule

**ALL artifacts MUST be written under `{output_dir}/`.** Never write files directly to the project root or any path outside `outputs/`.

• `{output_dir}` is the **absolute path** stored in `.workspace.json` at the output directory root.
• **Before writing any file**: if `{output_dir}` is uncertain (e.g., after context compression), recover it:

1. `Glob` for `outputs/*/.workspace.json`, select the most recently modified match. 2. `Read` the file and extract `output_dir`.

• **Subagent prompts and sub-skill invocations**: always include the absolute `{output_dir}` path.

When this skill is invoked, execute the full research pipeline below. **Always pause for user confirmation between phases.**

---

Phase Gate Protocol

See §PhaseGate in shared rules. Phase-specific checklists:

| Phase | Checklist Items | |:------|:----------------| | **Plan** | Completeness (all objectives addressed), methodology soundness, resource feasibility, risk identification | | **Implement** | Code correctness, alignment with plan, error handling, dependency management | | **Execute** | Exit code 0, `results/` populated (or EXISTING/PARTIAL with user acknowledgment), `pre_execution_status.json` written | | **Test** | Tier 1 unit test coverage, edge case handling, Common Restrictions fulfilled (plot_manifest.json, dual format, dependency spec), result reproducibility |

---

Resume Protocol

When `--resume <output_dir>` is provided, the pipeline skips initialization and infers the current phase from the **presence of key artifact files** in the output directory. This avoids requiring the LLM to maintain a separate state file — the artifacts themselves serve as checkpoints.

> **Unified semantics**: `--resume` always accepts the workspace root directory (e.g., `outputs/topic_20260309_v1/`). Whether resuming a research pipeline or a write sub-pipeline, the same root path is used. The system infers the correct sub-context internally.

**Phase inference rules** (evaluated top-down; first match wins):

| Condition | Inference | Action | |:----------|:----------|:-------| | `report.md` exists | Pipeline complete | Inform user; offer to re-run specific phases | | `plots/plot_manifest.json` exists | Test phase complete | Resume from the Report phase | | `results/pre_execution_status.json` exists (or `pre_execution_status.md` for legacy v0.8.x) | Execute phase complete | Resume from the Test phase | | `src/` contains at least one source file | Implement phase complete | Resume from the Execute phase | | `plan/research_plan.md` exists | Plan phase complete | Resume from the Implement phase