magi-researchers

Research Explain Skill

Description

Generates high-quality explanations of concepts using Gemini and Codex in parallel (Phase 1: MAGI strategy exploration), then synthesizes a single-voice explanation with Claude (Phase 2: convergent generation).

Usage

/research-explain "concept" [--domain physics|ai_ml|statistics|mathematics|paper] [--audience general-public|high-school|undergraduate|phd-student|researcher|expert|"free text"] [--weights '{"clarity":0.2,"accuracy":0.2}'] [--depth low|medium|high|max] [--personas N] [--claude-only] [--substitute "Gemini -> Opus"]

Arguments

• $ARGUMENTS — The concept to explain and optional flags:
• --domain — Knowledge domain (physics, ai_ml, statistics, mathematics, paper). Auto-inferred if omitted.
• --audience — Target audience (default: phd-student):
• 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 (default)
• researcher — Active researcher familiar with the field
• expert — Deep specialist in the exact sub-field
• "free text" — Any custom audience description (e.g., "medical doctors learning ML")
• --weights — JSON object of scoring weights for explanation quality ranking. Keys: clarity, accuracy, depth, accessibility, completeness, engagement. Values must sum to 1.0. If omitted, Claude analyzes the prompt and audience to recommend adaptive weights for user confirmation (see Step 0a).
• --depth — Controls explanation pipeline depth (default: medium):
• low — Skip Phase 1 entirely; Claude generates explanation directly
• medium — Full MAGI (parallel brainstorm + cross-review) → explanation
• high — MAGI + adversarial debate → explanation with misconceptions section
• max — Hierarchical MAGI-in-MAGI: N persona subagents → meta-review + debate → multi-perspective deep dive
• --personas N|auto — Number of explanation-specialist subagents for --depth max (default: auto, range: 2-4). When auto, Claude analyzes the concept to determine the optimal persona count. Ignored for other depth levels.
• --claude-only — Replace all Gemini/Codex MCP calls with Claude Agent subagents. Use when external model endpoints are unavailable or for a Claude-only workflow. Two subagents with distinct cognitive styles (Creative-Divergent and Analytical-Convergent) ensure perspective diversity.
• --substitute "Agent -> Opus" — Replace a specific MAGI agent with Claude (Opus). Accepted: "Gemini -> Opus", "Codex -> Opus". Can be specified multiple times. If both substituted, equivalent to --claude-only.

Instructions

Shared rules: Read ${CLAUDE_PLUGIN_ROOT}/shared/rules.md before starting. §MCP, §Claude-Only, §LaTeX, §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 in shared rules. Additionally:

• Codex: Use mcp__codex-cli__ask-codex for analysis/review.
• Visualization (if plots are generated): See §Visualization.
• When to search: concept definitions, pedagogical resources, common misconceptions, recent breakthroughs, related concepts, fact-checking claims

Claude-Only Mode

See §Claude-Only and §Substitute in shared rules. This skill uses Teacher/Critic asymmetric roles (see Step 0b).

LaTeX Formatting Rules

See §LaTeX in shared rules.

Reusable Templates

| ID | Name | Purpose | |---|---|---| | T1 | Audience Weight Defaults | Per-audience baseline weights table | | T2 | Step 0a Procedure | Full adaptive weight recommendation logic (signal table, normalization, save format) | | T3 | explanation.md Template | Section structure, word count targets, quality checklist | | T4 | Output File Trees | Expected artifact layout per depth level |

Read references/templates.md for full definitions.

When this skill is invoked, follow these steps exactly:

Step 0: Setup

1. Parse the concept to explain from $ARGUMENTS. If a --domain flag is provided, note the domain (physics, ai_ml, statistics, mathematics, paper). Otherwise, infer the domain from the concept.
2. Pipeline context detection: If an {output_dir} was provided by the calling context and .workspace.json already exists at the output root, skip directory creation and write to {output_dir}/explain/ instead of creating a new versioned directory.
3. Create the output directory: outputs/{sanitized_concept}_{YYYYMMDD}_v{N}/explain/
4. Sanitize the concept: lowercase, replace spaces with underscores, remove special characters, truncate to 50 chars.
5. Use today's date in YYYYMMDD format.
6. Version: Glob for outputs/{sanitized_concept}_{YYYYMMDD}_v*/ and set N = max existing + 1 (start at v1).
7. Write .workspace.json at the output directory root:

``json { "output_dir": "{absolute_path}", "skill": "research-explain", "concept": "{original_concept}", "domain": "{domain}", "audience": "{audience}", "depth": "{depth}", "created_at": "{ISO-8601}" } ``

1. If a domain template exists at ${CLAUDE_PLUGIN_ROOT}/templates/domains/{domain}.md, read it for context.
2. Parse --audience: Accept general-public, high-school, undergraduate, phd-student, researcher, expert, or any quoted free-text string (default: phd-student). The audience propagates into every prompt, persona casting, weight defaults, and the final explanation.
3. Parse --weights:
4. If --weights is explicitly provided: Validate that keys are a subset of {clarity, accuracy, depth, accessibility, completeness, engagement} and values sum to 1.0. Save immediately to explain/weights.json with metadata:

``json { "weights": { "<user-provided weights>" }, "_meta": { "method": "explicit", "domain": "<detected domain>", "audience": "<detected audience>" } } `` Skip Step 0a entirely.

• If --weights is not provided: Load the audience baseline from T1 in references/templates.md as a reference only (do not save yet — Step 0a handles saving after user confirmation).
• Parse --depth: Accept low, medium, high, or max (default: medium).
• low — Skip Phase 1 entirely; Claude generates explanation directly (jump to Step 2)
• medium — Full MAGI + one-shot cross-review → strategy synthesis → explanation
• high — Full MAGI + cross-review + adversarial debate → strategy synthesis → explanation with misconceptions
• max — Hierarchical MAGI-in-MAGI pipeline (Steps 1-max-a through 1-max-d replace Steps 1a/1b/1b+/1c)
• Parse --personas N|auto: Accept integer 2-4 or the string auto (default: auto). Only used when --depth max; ignored otherwise.
• If auto: Defer persona count determination to Step 0b, where Claude analyzes the concept's complexity, number of distinct pedagogical angles, and audience needs to select the optimal N (2-4).
• If an explicit integer is given: Use that value directly.
• Parse --claude-only: Boolean flag (default: false). When present, all Gemini/Codex MCP calls are replaced with Claude Agent subagents. See the Claude-Only Mode section above for the replacement table and cognitive style definitions.

Step 0a: Adaptive Weight Recommendation

If --weights was explicitly provided: Skip this step entirely (weights already saved in Step 0).

Full procedure: Read T2 in references/templates.md for the signal detection table, normalization rules, user confirmation flow, and weights.json save format.

When --weights is omitted: detect concept/audie