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:
   ```json
   {
     "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 `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).
8. **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)
9. **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.
10. **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/audience signals → adjust baseline weights → present comparison table → ask user for confirmation (Accept recommended / Use audience defaults / Custom JSON) → save to `explain/weights.json`.

### Step 0b: Dynamic Persona Casting

After setup, Claude analyzes the concept, domain, and audience to assign specialist personas:

**For `--depth low`:** Skip this step entirely.

**For `--depth medium|high` (2 personas — asymmetric Teacher/Critic roles):**

1. Analyze the concept's sub-topics, prerequisite structure, common misconceptions, and audience needs.
2. Assign a **Teacher persona (Agent A / Gemini)** — an expert communicator profile suited for explaining this concept to the target audience (e.g., "Richard Feynman — Intuitive Physics Explainer" or "3Blue1Brown-style Visual Mathematics Educator"). The Teacher's job is to **draft the best possible explanation**.
3. Assign a **Critic persona (Agent B / Codex)** — a pedagogical analyst profile suited for finding flaws in explanations (e.g., "George Pólya — Mathematical Problem-Solving Analyst" or "Cognitive Science Assessment Specialist"). The Critic's job is to **identify prerequisites, misconceptions, confusion neighbors, and calibration questions**.
4. Each persona definition should include: name/title, expertise areas (3-5 bullet points), and a guiding question that shapes their perspective. **Name the persona after a real historical figure (위인) whose work is closely related to the persona's domain**. This immediately signals the persona's intellectual lineage and communication style.
5. Personas are **complementary**: the Teacher builds understanding, the Critic stress-tests it.
6. **If `--claude-only`**: Relabel the personas in `explain/personas.md`:
   - "Teacher persona (Gemini)" → "Subagent A (Creative-Divergent, Teacher)"
   - "Critic persona (Codex)" → "Subagent B (Analytical-Convergent, Critic)"
   - Include the cognitive style directive in each persona definition so subagents receive it directly.
7. Save to `explain/personas.md`.

**For `--depth max` (N personas):**
> **Read `references/depth_max.md` — "Step 0b (depth max)" section** for the full N-persona casting procedure (N selection heuristic, persona archetypes N=2/3/4, definition requirements, claude-only relabeling).

### Step 1a: Parallel Asymmetric Analysis (`--depth medium|high|max`)

> **If `--depth low`**: Skip this step entirely and proceed to Step 2.
> **If `--depth max`**: Skip this step — use Steps 1-max-a through 1-max-d instead (read `references/depth_max.md`).

Execute these two calls **simultaneously** (in the same message). **Prepend the assigned persona** from `explain/personas.md` to each prompt.

**Agent A — Teacher Draft (Gemini):**
```
mcp__gemini-cli__ask-gemini(
  prompt: "[Persona: {teacher_persona_name} — {teacher_persona_expertise}]
Guiding question: {teacher_guiding_question}
Target audience: {audience}

Domain context: @{domain_template_path}

Concept to explain: {concept}

You are a master explainer. Generate a comprehensive draft explanation of this concept for the specified audience. Your explanation should:

1. **Core Explanation**: Build understanding from first principles appropriate to the audience level. Use analogies, examples, and progressive complexity.
2. **Key Intuitions**: What are the 2-3 most important intuitions the audience must grasp?
3. **Mathematical Formalism** (if applicable): Include relevant equations with clear notation explanations. Follow LaTeX formatting rules: inline math with $...$ and display equations with $$ on separate lines.
4. **Concrete Examples**: Provide 2-3 worked examples or real-world applications.
5. **Connections**: How does this concept relate to concepts the audience likely already knows?

Write for maximum clarity and understanding. Use the persona's communication style.",
  model: "gemini-3.1-pro-preview"  // fallback: "gemini-2.5-pro" → Claude
)
```
> Note: Omit the `Domain context: @{domain_template_path}` line from the prompt when no domain template exists.

**Agent B — Critic Analysis (Codex):**
```
mcp__codex-cli__ask-codex(
  prompt: "[Persona: {critic_persona_name} — {critic_persona_expertise}]
Guiding question: {critic_guiding_question}
Target audience: {audience}

Domain context: @{domain_template_path}

Concept to explain: {concept}

You are a pedagogical analyst and explanation critic. Generate a comprehensive critical analysis covering:

1. **Prerequisites Map**: What concepts must the audience understand before this one? List in dependency order. For each, note whether the audience level likely already has it.
2. **Common Misconceptions** (at least 5): For each misconception:
   - State the misconception clearly
   - Explain why it is plausible (what leads people to believe it)
   - Explain precisely why it is wrong
   - Provide a corrective reframing
3. **Confusion Neighbors**: Concepts that are commonly confused with this one. For each pair:
   - This concept IS NOT [confused concept]
   - Key distinguishing feature
4. **Precision-Accessibility Tradeoffs**: Where must an explanation sacrifice precision for accessibility at this audience level? What simplifications are acceptable vs. dangerous?
5. **Calibration Questions** (5-10): Questions that test genuine understanding (not just recall). Include expected correct answers and common wrong answers with explanations of what each wrong answer reveals about the student's misunderstanding.",
  model: "gpt-5.4"
)
```
> Note: Omit the `Domain context: @{domain_template_path}` line from the prompt when no domain template exists.

> Note: If Codex MCP is unavailable, fall back to `mcp__gemini-cli__ask-gemini` with the Gemini fallback chain and critic-focused framing.

> **If `--claude-only`**: Per §SubagentExec, spawn **simultaneously**:
> - **A** (CD, Teacher): Draft explanation of {concept} for {audience} using persona. Read domain template. Deliverables: 1.Core Explanation (first principles, analogies, progressive complexity), 2.Key Intuitions (2-3), 3.Mathematical Formalism (LaTeX), 4.Concrete Examples (2-3 worked), 5.Connections to audience's existing knowledge. Use persona's communication style. Save to `explain/gemini_ideas.md`.
> - **B** (AC, Critic): Critical analysis for {concept}/{audience} using persona. Deliverables: 1.Prerequisites Map (dependency order; note which audience likely has), 2.Common Misconceptions (≥5; each: statement → why plausible → why wrong → corrective reframing), 3.Confusion Neighbors (per pair: "IS NOT" + key distinguishing feature), 4.Precision-Accessibility Tradeoffs, 5.Calibration Questions (5-10; each: question + correct answer + common wrong answers + what each wrong answer reveals). Save to `explain/codex_ideas.md`.

Save results to:
- `explain/gemini_ideas.md` — Teacher's (or Subagent A's) draft explanation with header noting source, persona, and timestamp
- `explain/codex_ideas.md` — Critic's (or Subagent B's) analysis with header noting source, persona, and timestamp

### Step 1b: Cross-Check (`--depth medium` or `--depth high` only)

> **If `--depth low`**: Skip this step entirely and proceed to Step 2.

**Pre-check**: Verify `gemini_ideas.md` and `codex_ideas.md` both exist and are non-empty before proceeding. If either is missing, re-run only the failed agent from Step 1a.

After both Phase 1a results are saved, execute these two calls **simultaneously**. **Prepend the assigned persona** to each review prompt:

**Teacher reviews Critic's analysis (Round 1):**
```
mcp__gemini-cli__ask-gemini(
  prompt: "[Persona: {teacher_persona_name} — {teacher_persona_expertise}]
Target audience: {audience}

Review the following critical analysis of an explanation for: {concept}

@{output_dir}/explain/codex_ideas.md

For each item in the Critic's analysis:
1. **Misconceptions**: Are these real misconceptions at this audience level? Are any missing? Would your explanation actually trigger any of these?
2. **Prerequisites**: Agree/disagree with the prerequisite ordering? Are any prerequisites overestimated or underestimated for this audience?
3. **Confusion Neighbors**: Are these the right confusion neighbors? Suggest additions or removals.
4. **Precision-Accessibility Tradeoffs**: Are the identified tradeoffs fair? Where would you push back?
5. **Calibration Questions**: Would your explanation enable the audience to answer these correctly? Flag any questions that are unfair for the audience level.

Also note: What aspects of the Critic's analysis should change your draft explanation?",
  model: "gemini-3.1-pro-preview"  // fallback: "gemini-2.5-pro" → Claude
)
```

**Critic reviews Teacher's draft (Round 1):**
```
mcp__codex-cli__ask-codex(
  prompt: "[Persona: {critic_persona_name} — {critic_persona_expertise}]
Target audience: {audience}

Review the following draft explanation of: {concept}

@{output_dir}/explain/gemini_ideas.md

Evaluate the Teacher's explanation on these dimensions:
1. **Accuracy**: Are there any incorrect statements, oversimplifications that cross into inaccuracy, or misleading analogies?
2. **Completeness**: Does it cover all essential aspects? What critical gaps exist?
3. **Audience Calibration**: Is the language, depth, and assumed knowledge appropriate for {audience}?
4. **Misconception Risk**: Does any part of the explanation inadvertently reinforce common misconceptions?
5. **Analogy Fidelity**: Do the analogies accurately map to the concept? Where do they break down, and are those breakdown points acknowledged?
6. **Progressive Structure**: Does the explanation build understanding in the right order? Are there logical jumps?

For each issue found, provide:
- The specific problematic passage
- Why it's problematic
- A suggested fix",
  model: "gpt-5.4"
)
```

> Note: If Codex MCP is unavailable, fall back to `mcp__gemini-cli__ask-gemini` with the Gemini fallback chain.

> **If `--claude-only`**: Per §SubagentExec, spawn **simultaneously**:
> - **A** (CD, Teacher reviewing Critic): Read `codex_ideas.md`. Review all 5 sections: misconceptions (real at this level? missing?), prerequisites (ordering? over/underestimated?), confusion neighbors (additions/removals?), precision-accessibility tradeoffs (fair?), calibration questions (answerable from your explanation?). Also: what should change in your draft? Save to `explain/gemini_review_of_codex.md`.
> - **B** (AC, Critic reviewing Teacher): Read `gemini_ideas.md`. Evaluate 6 dimensions: accuracy, completeness, audience calibration, misconception risk, analogy fidelity (where do analogies break?), progressive structure (logical jumps?). Per issue: specific passage + why problematic + suggested fix. Save to `explain/codex_review_of_gemini.md`.

Save results to:
- `explain/gemini_review_of_codex.md`
- `explain/codex_review_of_gemini.md`

### Step 1b+: Adversarial Debate (`--depth high` only)

> **If `--depth low` or `--depth medium`**: Skip this step entirely.

After Round 1 cross-review, Claude identifies the **top 3 points of disagreement** between the Teacher and Critic, focusing on:
- **Misconception risk**: Disagreement on whether an explanation approach reinforces misconceptions
- **Analogy fidelity**: Disagreement on whether an analogy is accurate enough or dangerously misleading
- **Precision-accessibility tradeoff**: Disagreement on where the acceptable simplification boundary lies for this audience

**Save the disagreement summary to `explain/disagreements.md`** before the debate calls.

Execute Round 2 **simultaneously**:

**Teacher Round 2 — Defend/Concede/Revise:**
```
mcp__gemini-cli__ask-gemini(
  prompt: "[Persona: {teacher_persona_name}]
Target audience: {audience}

You (Teacher) and the Critic reviewed each other's work on explaining: {concept}

Here are the top 3 points of disagreement:

@{output_dir}/explain/disagreements.md

For each disagreement:
1. **Defend** your pedagogical choice if you believe it best serves understanding for this audience, providing evidence from learning science or teaching experience
2. **Concede** if the Critic's objection reveals a genuine accuracy or misconception risk, explaining why
3. **Revise** your approach to a new position that balances clarity and accuracy if appropriate

Your original review:
@{output_dir}/explain/gemini_review_of_codex.md

Critic's review of your draft:
@{output_dir}/explain/codex_review_of_gemini.md",
  model: "gemini-3.1-pro-preview"  // fallback chain applies
)
```

**Critic Round 2 — Defend/Concede/Revise:**
```
mcp__codex-cli__ask-codex(
  prompt: "[Persona: {critic_persona_name}]
Target audience: {audience}

You (Critic) and the Teacher reviewed each other's work on explaining: {concept}

Here are the top 3 points of disagreement:

@{output_dir}/explain/disagreements.md

For each disagreement:
1. **Defend** your objection if you believe the accuracy/misconception risk is genuine, providing specific examples of how learners are misled
2. **Concede** if the Teacher's pedagogical choice genuinely aids understanding without significant accuracy cost, explaining why
3. **Revise** your assessment to a new position that respects both rigor and accessibility if appropriate

Your original review:
@{output_dir}/explain/codex_review_of_gemini.md

Teacher's review of your analysis:
@{output_dir}/explain/gemini_review_of_codex.md",
  model: "gpt-5.4"
)
```

> **If `--claude-only`**: Per §SubagentExec, spawn **simultaneously**:
> - **A** (CD, Teacher Round 2): Read `disagreements.md` + `gemini_review_of_codex.md` + `codex_review_of_gemini.md`. Per disagreement: Defend (with learning science evidence) / Concede (if genuine accuracy or misconception risk) / Revise (balance clarity + accuracy). Save to `explain/debate_round2_gemini.md`.
> - **B** (AC, Critic Round 2): Read same 3 files. Per disagreement: Defend (with specific examples of how learners are misled) / Concede (if pedagogical choice genuinely aids understanding without accuracy cost) / Revise (balance rigor + accessibility). Save to `explain/debate_round2_codex.md`.

Save results to:
- `explain/debate_round2_gemini.md`
- `explain/debate_round2_codex.md`

### Steps 1-max-a through 1-max-d: Hierarchical MAGI-in-MAGI (`--depth max` only)

> **Skip unless `--depth max`**. Read `references/depth_max.md` for all four steps.
> These steps replace Steps 1a/1b/1b+/1c entirely when `--depth max` is active.

Summary of what runs:
- **1-max-a**: Spawn N persona subagents in parallel; each runs a self-contained mini-MAGI pipeline (Gemini draft + Codex analysis + cross-review + conclusion).
- **1-max-b**: Collect and verify all N conclusions; build `all_conclusions.md` consolidated file.
- **1-max-c**: Layer 2 meta-reviews (Gemini + Codex simultaneously) → extract top 3 cross-persona disagreements → adversarial debate.
- **1-max-d**: Layer 3 enriched synthesis: weighted scoring across all strategies → `explain/synthesis.md` with 9-section structure including traceability table.

### Step 1c: Strategy Synthesis

> **If `--depth max`**: Skip — synthesis is produced by Step 1-max-d (read `references/depth_max.md`).
> **If `--depth low`**: Skip — proceed directly to Step 2.

1. Read all available documents:
   - Always: `gemini_ideas.md`, `codex_ideas.md`
   - If `--depth medium` or `high`: `gemini_review_of_codex.md`, `codex_review_of_gemini.md`
   - If `--depth high`: `debate_round2_gemini.md`, `debate_round2_codex.md`
   - Always: `weights.json`, `personas.md`
2. Load `weights.json` and extract the `"weights"` object. Use the weights to compute a **weighted score** for each explanation strategy:
   - For each candidate strategy, rate it on each weight dimension (0-10 scale): clarity, accuracy, depth, accessibility, completeness, engagement
   - Compute the weighted sum: `score = Σ(weight_i × rating_i)`
   - Rank strategies by weighted score
3. Synthesize into an **explanation strategy document** that includes:
   - **Personas Used** — brief summary of assigned Teacher and Critic personas
   - **Scoring Weights** — the weights used for ranking (from `weights.json`), including `_meta.method`
   - **Recommended Explanation Strategy** (ranked by weighted score, showing score breakdown):
     - Best analogies and examples to use
     - Optimal explanation structure/ordering
     - Key intuitions to emphasize
   - **Prerequisites Summary** — consolidated prerequisite chain for the target audience
   - **Misconception Inventory** — merged and deduplicated misconceptions from both agents
   - **Confusion Neighbors** — consolidated confusion neighbor list
   - **Consensus Points** — pedagogical choices both agents agreed on
   - **Divergence Points** — areas of disagreement and how to resolve them
   - **Debate Resolution** (`--depth high` only) — for each of the 3 debated disagreements, document the final resolution: who conceded, what was revised, and the synthesized position
   - **Calibration Questions** — best questions from the Critic's analysis, selected for the target audience
4. Save to `explain/synthesis.md`.

### Step 2: Explanation Generation

Claude reads all Phase 1 artifacts and generates the final explanation. This step is **always** executed by Claude directly (never delegated to MCP tools) to ensure a single authoritative voice.

**For `--depth low`** (no Phase 1 artifacts):
1. Read `explain/weights.json` (if available).
2. If a domain template exists, read it for context.
3. Generate `explain/explanation.md` directly based on the concept, audience, and domain.

**For `--depth medium|high|max`** (Phase 1 artifacts available):
1. Read `explain/synthesis.md` and all referenced artifacts.
2. Read `explain/weights.json` to understand the quality priorities.

**Generate `explain/explanation.md`**: Read **T3** in `references/templates.md` for the full section structure, word count targets per depth, and quality checklist.

Save to `explain/explanation.md`.

### Step 3: User Feedback

Present the explanation to the user with:
- A concise summary of what was generated (concept, audience, depth, word count)
- The location of all output files
- Clear options for refinement:
  - **Adjust audience level**: Re-generate for a different audience
  - **Adjust depth**: Add/remove sections
  - **Refine specific section**: Focus on improving one part
  - **Expand a topic**: Deep-dive into a specific aspect mentioned in the explanation

Wait for user input before proceeding.

## Output Files

> See **T4** in `references/templates.md` for full artifact trees per depth level (`low`, `medium`, `high`, `max`).

Quick summary:
- `--depth low`: `weights.json` + `explanation.md`
- `--depth medium`: adds `personas.md`, `gemini_ideas.md`, `codex_ideas.md`, cross-reviews, `synthesis.md`
- `--depth high`: adds `disagreements.md`, `debate_round2_*.md`
- `--depth max`: adds `persona_N/` subdirs, `all_conclusions.md`, meta-reviews, meta-debate files