/research-explain

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/`

• Sanitize the concept: lowercase, replace spaces with underscores, remove special characters, truncate to 50 chars.
• Use today's date in YYYYMMDD format.
• Version: Glob for `outputs/{sanitized_concept}_{YYYYMMDD}_v*/` and set N = max existing + 1 (start at v1).

4. Write `.workspace.json` at the output directory root:

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

5. If a domain template exists at `${CLAUDE_PLUGIN_ROOT}/templates/domains/{domain}.md`, read it for context. 6. **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. 7. **Parse `--weights`**:

• **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