research-copilot 0.2.17 → 0.2.21

package/lib/skills/builtin/academic-marp-slides/SKILL.md

@@ -0,0 +1,933 @@
+---
+name: academic-marp-slides
+description: "Create or revise high-quality academic presentation slides in Markdown using Marp, following a disciplined multi-phase workflow. Use when the user needs conference talk slides, lab meeting decks, thesis defense presentations, research seminars, invited talks, OR wants to revise an existing Marp slide file. Enforces Assertion-Evidence structure and Mayer's multimedia learning principles. For teaching/lecture slides use `teaching-marp-slides`; for written documents use `paper-writing` or `scientific-writing`; for individual figures use `scientific-visualization`."
+category: Presentation
+tags: [Marp, Slides, Presentation, Conference Talk, Lab Meeting, Thesis Defense, Seminar, Research Talk, Assertion-Evidence, 做PPT, 学术幻灯片, 演示文稿, 学术报告]
+triggers: [make slides, create presentation, conference talk, lab meeting slides, thesis defense, research presentation, seminar slides, marp, slide deck, revise slides, edit slides, improve slides, 做幻灯片, 做报告, 学术演讲, 修改幻灯片, PPT]
+depends: [scientific-visualization, scientific-schematics]
+license: MIT
+metadata:
+    skill-author: Dong Dai
+    based-on: robonuggets/marp-slides, Alley Assertion-Evidence, Mayer multimedia learning principles
+---
+
+# Academic Research Presentation Slides with Marp
+
+## Core Principle
+
+**Slides are not documents.** They are visual aids for a spoken narrative. A good slide deck cannot be produced in one pass — it requires iteration through distinct phases, each with a different goal. This skill enforces a **phased workflow** that separates thinking (what to say) from structuring (what order) from visual design (how it looks). Skipping phases produces the flat, overstuffed, logically-loose decks that plague academic talks.
+
+The two theoretical anchors:
+
+1. **Assertion-Evidence structure** (Michael Alley): Every slide title is a **complete sentence** stating a claim. The slide body is **visual evidence** for that claim. No bullet-point lists of topics.
+2. **Mayer's multimedia learning principles**: Images + spoken explanation beats on-screen text read aloud. Reduce redundancy, maximize signaling, keep related elements spatially close.
+
+**Violating either of these is the most common reason academic slides fail.**
+
+> **Note on Dry Run**: The user explicitly handles delivery rehearsal and validation themselves after receiving the draft. This skill therefore stops at a polished draft and does not prescribe dry-run steps. The user will test the deck and come back with revisions (Revise Mode).
+
+---
+
+## When to Use This Skill
+
+- Conference talks, invited talks, workshop presentations
+- Lab meetings, group meetings, research seminars
+- Thesis defenses, qualifying exams
+- Converting a paper/preprint into a talk
+- **Revising** an existing Marp research slide deck
+
+### When NOT to Use
+
+| Need | Use Instead |
+|------|-------------|
+| Teaching / lecture / classroom slides | `teaching-marp-slides` |
+| Written paper, report, grant | `paper-writing`, `scientific-writing`, or `research-grants` |
+| One standalone figure | `scientific-visualization`, `matplotlib`, or `seaborn` |
+| Diagram / schematic only | `scientific-schematics` |
+| Poster (static large-format) | Ask user before proceeding — Marp can do it but dedicated poster tools are better |
+| PPTX that user will keep editing in PowerPoint | Marp PPTX export loses styling; warn the user first |
+
+---
+
+## Phase 0: Mode Detection (Do This First, Every Time)
+
+Before anything else, determine which mode applies:
+
+### Signals for **Revise Mode**
+- User attached or referenced an existing `.md` Marp file
+- User says "change/fix/improve/update [existing slides]"
+- User says "the deck I made…" / "slide 5 should…" / "this section is…"
+- User pastes Marp Markdown and asks for edits
+
+### Signals for **Create Mode**
+- User describes a paper, research, or topic but has no existing deck
+- User says "make slides for my talk on…" / "help me prepare a presentation"
+- No Marp source file has been provided or created earlier in the conversation
+
+If ambiguous, **ask**:
+> "Are we starting a new deck from scratch, or revising an existing one? If existing, please share the .md source."
+
+Then route to the appropriate mode below.
+
+---
+
+## Context Gate (Required Before Create Mode)
+
+**Good slides do not start from scratch — they are rooted in existing context.** Before entering Phase 1, run the context sweep below and summarize what you found (and what you could not find) to the user. A one-paragraph summary up front saves a Phase 3 rewrite later.
+
+The sweep has three tiers. **Do all of tier 1 always; do tier 2 whenever it is cheap and plausibly relevant; only do tier 3 if tier 1+2 left real gaps.** Report at each tier — do not silently skip.
+
+### Tier 1 — Local context (always do, zero cost)
+
+Four distinct local stores. Check each one — they don't overlap:
+
+1. **Structured memory** — `.research-pilot/memory/` holds long-lived user facts (co-author names, venue preferences, recurring style choices, prior talk themes). Read `MEMORY.md` (the index) and open any memory files whose description looks relevant. These are persistent across sessions and override inferred defaults.
+2. **Papers wiki (RFC-005)** — the user's curated literature knowledge base. Use it as follows:
+   - `wiki_coverage` first if you don't know what's in it — returns the list of indexed topics/facets.
+   - `wiki_search` with the user's topic / method / key terms.
+   - `wiki_get` to pull a specific entry; `wiki_neighbors` to walk from a known entry to adjacent work; `wiki_source` to trace a claim back to the underlying paper.
+   - If the wiki tools return "Wiki not available", the workspace has no wiki — skip this substep and move on.
+3. **Artifacts (local literature + notes)** — call `artifact-search` scoped to `papers` and `notes` with the user's topic/method keywords. Hits here are the user's own saved papers, reading notes, and prior session outputs. Read the most relevant before asking the user anything.
+4. **Workspace files and session history** — scan:
+   - `.research-pilot/memory-v2/session-summaries/` for summaries of prior work on this topic
+   - `.research-pilot/memory-v2/focus/` for the user's current focus entries
+   - `.research-pilot/artifacts/tool-output/slides/` for any prior decks in this workspace (style reference)
+   - Any paper drafts, reading PDFs, or data files the user dropped into the workspace root — use `grep`/`find` for likely filenames.
+
+If any of these sources names a PDF/DOCX by path that is not yet an artifact, run `convert-document` on it first so its content becomes usable text.
+
+### Tier 2 — User confirmation + light expansion (do when gaps remain)
+
+**Ask the user once, in a batched message**, whether any of these additional inputs exist:
+- **Paper, preprint, or manuscript draft** for the research being presented (if not already found)
+- **Prior talk slides** from the same group (style, figure choices)
+- **Conference/venue style guide** (some conferences have templates)
+- **Target venue examples** (published keynotes from the same venue)
+
+**Plus, do a quick literature scan** if the slides will have a related-work section and tier 1 returned little:
+- Call the `literature-search` tool with the user's topic + method keywords, limited to ~5–10 hits. This is a *context-building* pass, not an exhaustive survey — pull titles, venues, and abstracts to understand where the work sits.
+- If `wiki_coverage` in tier 1 showed the wiki is well-populated on this topic, skip this step — the wiki already covers it.
+
+### Tier 3 — Online fallback (do only if needed for a specific gap)
+
+Use these only when a tier 1+2 gap is *load-bearing* for the deck (e.g., the user named a venue you've never heard of, or a result claim needs a citation nobody has):
+- `web_search` for venue style guides, conference CFPs, keynote examples, or recent news tied to the claim.
+- `web_fetch` on a specific URL the user mentioned or the search returned.
+
+Do not use tier 3 for general background — that belongs in `literature-search` or the wiki.
+
+### After the sweep — report and decide
+
+Write one short paragraph to the user:
+- **What I found:** [memory hits / wiki hits / artifact hits / workspace files / literature-search hits / web snippets]
+- **What I still need:** [specific gaps that would change the deck — e.g., "no prior slides from your group, so I'll guess at visual style unless you share one"]
+- **Proposed action:** either (a) proceed to Phase 1 now, or (b) pause while the user supplies one or two missing pieces
+
+If the sweep turns up nothing substantive and the user has nothing more to share, proceed — but flag it explicitly:
+> "No source material found locally or via a quick literature scan — I'll generate from scratch. Output will be generic and may need heavier revision. Consider sharing a paper draft, notes artifact, or a reference talk if possible."
+
+This flag tells the user what quality to expect and invites them to supply material before committing.
+
+## Working Posture (Applies to All Phases)
+
+Work like a junior presenter briefing a senior advisor — not like a machine executing a template.
+
+- **Surface assumptions before acting.** If you're inferring something the user didn't say (e.g., "I assume this is for specialists in your exact subfield"), state it.
+- **Name decisions and their rationale.** When choosing a narrative structure or an evidence type, say why you picked it and what else you considered.
+- **Flag unknowns.** If a slide needs a figure you don't have, mark it with a clear placeholder and a question to the user.
+- **Less is more.** Do not add filler content. Every slide, bullet, and figure must earn its place. If a slide feels empty, that's a composition problem to solve by re-layout — not by inventing content.
+
+These apply at every STOP AND CONFIRM gate.
+
+---
+
+# CREATE MODE
+
+Four phases. Each has a stop-and-confirm gate with the user. **Do not skip gates. Do not proceed to the next phase without explicit user approval — even if the answer seems obvious.**
+
+```
+Phase 1: Storyline   ──►  Outline on paper, no PPT    (25% of total time)
+Phase 2: Skeleton    ──►  Empty slide sequence         (15%)
+Phase 3: Content     ──►  Fill in figures + text       (40%)
+Phase 4: Polish      ──►  Visual refinement            (20%)
+```
+
+## Phase 1: Storyline
+
+**Goal**: Decide what story to tell before touching any slide software.
+
+**Tools allowed**: Prose outlines and assertion lists. **Do not create a `.md` file yet.**
+
+### Step 1.1 — Consolidated intake (ask everything up front, in one batch)
+
+Rather than asking questions one at a time and ping-ponging, ask for everything needed in a single structured request. If the user has already answered some of these in earlier messages or if the Context Gate surfaced them from artifacts, fill those in and only ask the remainder.
+
+**Required before moving on:**
+
+1. **Audience** — peers in subfield / adjacent field / broad scientific / funders / mixed
+2. **Talk length** — lightning 5 min / short 10–12 min / standard 15–25 min / invited 45–60 min / defense 45–60 min
+3. **Venue** — conference hall / seminar room / lab meeting / online — affects theme choice
+4. **The one-sentence thesis** — the single most important thing the audience should remember one week later. If the user can't articulate this, help them extract it from their paper/notes, but do not proceed until it exists.
+5. **2–3 supporting claims** that back up the thesis
+6. **Context material available** — paper draft, prior slides, reference talks (tie to Context Gate above)
+7. **Hard constraints** — mandatory slides (affiliation logos, funding acknowledgments), required sections (disclosures, conflicts)
+
+Batch these as one message. Do not begin drafting assertions until the user has answered the required items (1, 2, 4, 5) at minimum.
+
+### Step 1.2 — Draft the assertion list
+
+Write out **every slide's title as a complete declarative sentence**. Example:
+
+Bad (topic labels):
+- Introduction
+- Methods
+- Results
+- Discussion
+
+Good (assertions):
+- Predicting crystal structures beyond 30 atoms is infeasible with traditional CSP methods
+- Existing AI generative models for crystals lack symmetry and local-environment constraints
+- LEGO-xtal combines subgroup augmentation with SO(3)-descriptor pre-relaxation
+- From 25 known sp² carbon structures, we generated 1,741 new low-energy allotropes
+- We discovered four previously unknown negative-curvature graphite structures
+
+Each assertion will become exactly one slide in Phase 2. The audience should follow the logical thread by reading titles alone.
+
+### Step 1.3 — Propose 2–3 narrative structure options (let the user pick)
+
+Do not pick a single narrative unilaterally. Identify the 2–3 structures that plausibly fit the research, describe the trade-off, and let the user choose. This prevents committing to the wrong arc before the user has had a chance to weigh in.
+
+Candidate structures:
+
+| Structure | Best when… | Risk |
+|-----------|-----------|------|
+| **Problem-Method-Result** | Standard research with clear problem, clean methodology, quantitative result | Feels generic; no tension |
+| **Reversal** | Finding contradicts common belief or prior work | Requires a genuinely surprising result |
+| **Journey** | Exploratory work, serendipitous discovery, methodology paper | Can meander without strong editing |
+| **Comparison** | Benchmarks, head-to-head systems studies, framework papers | Audience may lose interest in the losers |
+
+Present the 2–3 most plausible candidates to the user with a one-line trade-off for each, then wait for their pick.
+
+### Step 1.4 — ★ STOP AND CONFIRM ★
+
+Present to the user before writing any Markdown. Structure the handoff like a junior-to-advisor briefing:
+
+**Proposal:**
+1. The one-sentence thesis
+2. The ordered list of assertion-style slide titles
+3. The chosen narrative structure (one of the candidates the user picked)
+4. Target slide count and time budget
+
+**Assumptions I made (tell me if any are wrong):**
+- [List any inferences — audience expertise level, what to omit, what to emphasize]
+
+**Open questions:**
+- [List anything still undecided — e.g., "unclear whether the negative result should be its own section or a subsection"]
+
+**Do not proceed to Phase 2 without explicit approval.** Fixing a broken storyline here costs minutes; fixing it in Phase 3 costs hours.
+
+**Persist the approved storyline.** After approval, call `artifact-create` with `type='note'` and a title like `Slides storyline — <talk title>`, storing the thesis, assertion list, and narrative choice. This gives the user a resumable checkpoint and makes the plan searchable in future sessions.
+
+### Phase 1 Checklist
+
+- [ ] Context Gate completed (workspace searched; source material confirmed or absence flagged)
+- [ ] Consolidated intake completed (audience, length, venue, thesis, supporting claims, context material, constraints)
+- [ ] One-sentence thesis is specific (not "we studied X")
+- [ ] Every planned slide has an assertion-style title
+- [ ] 2–3 narrative candidates were presented; user picked one
+- [ ] STOP gate briefing surfaced assumptions and open questions
+- [ ] User has approved the storyline
+- [ ] Approved storyline persisted as a note artifact
+
+---
+
+## Phase 2: Skeleton
+
+**Goal**: Translate the approved storyline into a Marp file where every slide exists but contains no visual content yet.
+
+**Tools allowed**: Create the `.md` file with minimum front matter. Use the default theme. **No images, no CSS tuning, no colors.**
+
+### Step 2.1 — Decide output location
+
+Write the Marp source to `<workspace>/.research-pilot/artifacts/tool-output/slides/<slug>.md` (create the `slides/` subfolder if it does not exist). Using the project artifact tree means the deck lives alongside other session outputs and can be discovered later with `artifact-search`.
+
+If the user has specified a different path, honor it — but mention this convention so they know where future decks will land by default.
+
+### Step 2.2 — Minimum front matter
+
+```markdown
+---
+marp: true
+theme: default
+paginate: true
+math: mathjax
+---
+```
+
+### Step 2.3 — One slide per assertion
+
+For each approved assertion from Phase 1:
+
+```markdown
+---
+
+# [Full assertion sentence from Phase 1]
+
+> PLACEHOLDER: [one sentence describing what evidence goes here]
+
+<!-- Speaker notes: key points to say aloud -->
+```
+
+### Step 2.4 — Add structural slides
+
+- **Title slide** (1) — use `<!-- _class: lead -->` and `<!-- _paginate: false -->`
+- **Outline slide** (1) — only if talk >20 min
+- **Section dividers** (1 per major section) — `<!-- _class: lead -->`
+- **Thank you / questions slide** (1)
+- **Backup slides** (2–5) clearly marked for anticipated Q&A
+
+### Step 2.5 — Check timing arithmetic
+
+Standard pacing: **~1 minute per content slide**.
+
+| Talk length | Content slides | Total incl. dividers |
+|-------------|----------------|----------------------|
+| 5 min | 5–7 | 6–8 |
+| 10–12 min | 8–12 | 10–14 |
+| 15–20 min | 13–18 | 16–22 |
+| 25 min | 18–22 | 22–27 |
+| 45–60 min (defense) | 30–45 | 40–55 |
+
+If skeleton is 30% over or under target, fix it now.
+
+### Step 2.6 — ★ STOP AND CONFIRM ★
+
+Show the user the skeleton (titles + placeholders only). Ask:
+
+- Does the logical flow from title to title still work when read in order?
+- Is any slide doing too much or too little?
+- Are there missing transitions?
+
+Wait for approval before Phase 3.
+
+### Phase 2 Checklist
+
+- [ ] Skeleton file written under `.research-pilot/artifacts/tool-output/slides/` (or user-specified path)
+- [ ] Every assertion has a slide
+- [ ] Every slide has a placeholder describing what visual evidence goes there
+- [ ] Slide count matches target time budget
+- [ ] Section dividers, title, thank-you slides in place
+- [ ] User has approved the skeleton
+
+---
+
+## Phase 3: Content
+
+**Goal**: Replace every placeholder with actual visual evidence (figures, tables, equations) and concise supporting text.
+
+**Tools allowed**: Embed figures, write text, build simple tables. **No theme/color polishing yet.**
+
+### Step 3.1 — For each slide, decide evidence type
+
+| Assertion claims… | Best evidence form |
+|-------------------|-------------------|
+| Quantitative comparison | Bar/line chart or table with bold winners |
+| Structural/spatial concept | Schematic diagram or annotated figure |
+| Procedural idea | Flowchart or numbered steps |
+| Theoretical result | Equation with labeled terms |
+| Qualitative contrast | Two-column before/after layout |
+| Discovery / example | Representative image + caption |
+
+### Step 3.2 — Source figures by priority (use project skills/tools)
+
+1. **Existing publication figures** from the paper draft or prior slides — but simplify: remove panels, enlarge fonts, trim legends. Publication figures are too dense for slides.
+2. **Fresh publication-quality figures** — delegate to project skills:
+   - For journal-style multi-panel plots → `load_skill('scientific-visualization')`
+   - For low-level custom plots → `load_skill('matplotlib')` or `load_skill('seaborn')`
+   - Export to `<workspace>/.research-pilot/artifacts/tool-output/slides/figures/` and embed with a relative path.
+3. **Fresh data-driven numbers or charts** — if a claim needs a computation or re-plot the user doesn't have yet, call the `data-analyze` tool first; persist its output, then embed it.
+4. **Schematics and concept diagrams** — call the `generate_diagram` tool (load `scientific-schematics` first for type-specific prompt guidance). Output format: PNG for final embed (recommended for slides — fixed, predictable visual), or `format: "svg"` when the author wants to hand-tweak labels / colors afterwards (writes a `.png` anchor sibling for diffing). Best quality requires `OPENAI_API_KEY`; without the key, SVG falls back to a chat-model-only path with reduced quality, or hand-write inline SVG using the Component Library below.
+5. **Related-work / citation slides** — use the `literature-search` tool to gather references with proper metadata; pull BibTeX/DOIs into speaker notes or a References backup slide.
+6. **Inline SVG / HTML components** — for metric cards, simple bar charts, timelines (see Component Library below).
+
+### Step 3.3 — Follow one-idea-per-slide limits
+
+Marp **silently clips** overflowing content. These are survival rules:
+
+- Max 6 bullet points (prefer 3–4)
+- Max 1 primary figure + ≤3 lines of supporting text
+- Max 1 table with ≤5 rows and ≤5 columns
+- Max 1 code block of ≤12 lines
+- Body text never below 0.7em
+
+If a slide violates these, **split it**. Never shrink text to fit.
+
+### Step 3.4 — Less is more (reject filler content)
+
+Every slide, bullet, figure, and icon must earn its place. Actively reject these filler patterns:
+
+- **Stat slop** — numbers or metrics included because "slides need data," not because they support the assertion
+- **Decorative icons** — small icons next to every bullet point that add no semantic meaning
+- **Padding bullets** — expanding 3 real points into 5 to "fill the slide"
+- **Restated titles** — a bullet that just rewrites the title in worse prose
+- **Generic agenda slides** — "Outline: Intro → Method → Results → Conclusion" on a 15-min talk wastes 90 seconds
+
+If a slide feels empty, fix it by **re-composing the layout** (larger figure, better whitespace, two-column split), never by inventing content. One thousand no's for every yes.
+
+### Step 3.5 — Apply Mayer non-redundancy
+
+Whatever you will say aloud must **NOT** also appear as on-screen text. On-screen text should only be:
+
+- Key numerical values and labels
+- Proper nouns and technical terms the audience might miss aurally
+- The single-sentence takeaway reinforcing the title
+
+Write spoken narration in speaker notes (HTML comments), not on the slide surface.
+
+### Step 3.6 — Write the takeaway line
+
+Every content slide needs a visible one-line takeaway that reinforces the title-assertion:
+
+```markdown
+# LEGO-xtal generates 1,741 new sp² allotropes from 25 starting structures
+
+![w:700](./figures/energy_distribution.png)
+
+**A ~70× expansion of the known low-energy sp² carbon space** using only symmetry augmentation and descriptor-guided pre-relaxation.
+```
+
+### Step 3.7 — ★ STOP AND CONFIRM ★
+
+Render the deck locally and show the user. Like Phase 1, include assumptions and open questions alongside the draft:
+
+**Deliverable:**
+- Rendered Marp deck with figures and text filled in (HTML preview at minimum)
+
+**Assumptions I made:**
+- [e.g., "I picked the left panel of Figure 3 because it shows the main result most cleanly; flag if you'd prefer the combined panel."]
+
+**Open questions:**
+- [e.g., "Slide 7 needs a schematic I don't have — should I draw a placeholder or wait for you to provide one?"]
+
+Ask the user to:
+
+- Flip through and confirm each slide delivers on its title-assertion
+- Flag any slide that feels too dense, too empty, or illogical
+- Note any figure that needs to be replaced or redrawn
+
+Wait for approval before Phase 4.
+
+### Phase 3 Checklist
+
+- [ ] Every slide has primary visual evidence
+- [ ] No slide violates the one-idea limits
+- [ ] No slide has more than ~30 English words (or ~50 CJK characters) of on-screen prose
+- [ ] Every slide has a takeaway line
+- [ ] Speaker notes exist for at least every results slide
+- [ ] All embedded figures resolve (no broken links)
+- [ ] User has reviewed the filled-in deck
+
+---
+
+## Phase 4: Polish
+
+**Goal**: Apply consistent visual styling. **No content changes at this stage.** If content still needs changes, return to Phase 3.
+
+### Step 4.1 — Choose and apply a theme
+
+| Venue | Theme |
+|-------|-------|
+| Conference auditorium, invited talk | **Dark theme** |
+| Lab meeting, classroom, well-lit room | **Light theme** |
+| Print handouts needed | **Light theme** |
+| Premium / keynote feel | **Dark theme** with single strong accent |
+
+Paste the full CSS block from the Theme System section. **Do not invent a new theme unless specifically requested** — the provided themes are tuned for legibility.
+
+### Step 4.2 — Enforce consistency
+
+- **Font consistency** — one heading font, one body font, one monospace
+- **Color consistency** — main + one accent. Semantic colors used the same way throughout.
+- **Figure styling** — axis font size, line weight, legend placement consistent across charts
+- **Spatial consistency** — titles, footers, pagination in same position everywhere
+
+### Step 4.3 — Readability checks
+
+- **Far-row test**: Zoom to 25%, squint. Anything unreadable is too small.
+- **Print test**: Export PDF, view greyscale. Color-only distinctions should still work (add shape/bold).
+- **Colorblind test**: Avoid red-green as sole distinguisher.
+- **Projector test**: Body text at least `#666` on light or `#94a3b8` on dark.
+
+### Step 4.4 — Add speaker notes and metadata
+
+```markdown
+<!-- Speaker note: Emphasize the 70× expansion. Pause after the number. Backup slide 3 has phonon validation if asked. -->
+```
+
+### Step 4.5 — Export
+
+```bash
+# HTML (best fidelity, use on presentation laptop)
+npx @marp-team/marp-cli slides.md --html --allow-local-files
+
+# PDF (backup + sharing) — ALWAYS export this too
+npx @marp-team/marp-cli slides.md --pdf --allow-local-files
+
+# PPTX (only if user will edit further in PowerPoint)
+npx @marp-team/marp-cli slides.md --pptx --allow-local-files
+```
+
+**Always export HTML + PDF.** Projector failures are common; PDF is the universal fallback.
+
+### Step 4.6 — Persist the final deliverable
+
+Call `artifact-create` with `type='tool-output'`, title `Slides — <talk title>`, and the final Markdown content. Record the exported HTML/PDF paths in the artifact body so the user can find them later via `artifact-search`.
+
+### Phase 4 Checklist
+
+- [ ] Theme CSS applied consistently
+- [ ] Fonts, colors, spacing consistent across all slides
+- [ ] Far-row and print tests pass
+- [ ] Speaker notes present for key slides
+- [ ] HTML + PDF both exported
+- [ ] Final deck persisted as a tool-output artifact
+- [ ] User has the final deliverables
+
+---
+
+# REVISE MODE
+
+**Goal**: Improve an existing deck without disturbing the user's intentional choices.
+
+**Guiding principle — Respect the user's work.** The user has already made hundreds of decisions. Change only what's requested or clearly broken. Do not rewrite to match Claude's style preferences.
+
+## Change-Size Classification
+
+Classify the request before editing:
+
+| Level | Meaning | Examples |
+|-------|---------|----------|
+| **L1 — Surface** | Typos, colors, rewordings, image resizing | "fix typos", "make accent green", "this figure too small" |
+| **L2 — Local** | Rework one slide, swap a figure, tighten bullets | "rewrite slide 7", "replace figure on slide 12" |
+| **L3 — Structural** | Reorder sections, add/remove slides, change narrative | "cut 5 min from the talk", "motivation should come after results" |
+| **Vague** | "feels off", "middle is boring", "too dense" | Diagnose first, propose a plan |
+
+Report which level you think applies before editing if it's anything beyond L1.
+
+## Quick Diagnosis Checklist
+
+When the user reports a problem but doesn't pinpoint it, run through this in order. Report findings before making edits.
+
+**Structural level**
+- [ ] Reading titles alone tells a coherent story?
+- [ ] Slide count matches stated talk length (±20%)?
+- [ ] Each section has a divider?
+- [ ] Results slides outnumber background slides?
+
+**Per-slide level (scan each content slide)**
+- [ ] Title is an assertion (complete sentence with a claim)?
+- [ ] Main visual evidence present and supports the title?
+- [ ] Body text ≤30 English words (or ~50 CJK chars)?
+- [ ] Takeaway line present?
+- [ ] Not violating one-idea-per-slide limits (≤6 bullets, ≤1 primary figure)?
+
+**Visual level**
+- [ ] Fonts consistent throughout?
+- [ ] One accent color used consistently?
+- [ ] No content clipped at slide edges?
+- [ ] Figures legible (axis labels readable)?
+
+Flag any failing items. Let the user pick which to fix.
+
+## Revise Mode Workflow
+
+1. **Load and read** the existing `.md` file completely.
+2. **Classify the request** (L1 / L2 / L3 / vague).
+3. **If L3 or vague**: run diagnosis, propose a plan, wait for user confirmation.
+4. **If L1 or L2 with specific targets**: execute directly.
+5. **Use targeted edits** — not full-file rewrites. Full rewrites are a red flag that you are over-reaching.
+6. **Report changes** as a compact, 1-indexed diff summary (e.g., "Slide 5: replaced figure; Slide 8: split into 8a + 8b").
+7. **Do not polish unrelated slides** unless the user asked for a consistency pass.
+
+## Common Revise Requests and How to Handle
+
+| Request | Classification | Action |
+|---------|---------------|--------|
+| "Fix typos" | L1 | Scan all, fix, report count |
+| "Change the accent color to green" | L1 | Update theme CSS only |
+| "This figure is too small" | L2 | Adjust `w:` value, offer to simplify figure |
+| "Rewrite slide 7's bullets" | L2 | Rewrite only slide 7, preserve style |
+| "The middle feels too dense" | L2 vague | Diagnose first: flag overloaded slides, propose splits |
+| "Add a slide about X" | L3 | Ask where it goes, what evidence it needs, confirm title |
+| "Cut 5 minutes from the talk" | L3 | Identify cuttable slides, confirm before removing |
+| "Reorganize so method comes before motivation" | L3 | Confirm the user really wants this (non-standard arc), then reorder |
+
+---
+
+# Reference Material (Shared by Both Modes)
+
+## Marp Syntax Essentials
+
+### Front matter
+
+```markdown
+---
+marp: true
+theme: default
+paginate: true
+math: mathjax
+size: 16:9
+style: |
+  /* CSS block — paste from Theme System below */
+---
+```
+
+### Per-slide directives
+
+```markdown
+<!-- _class: lead -->            # centered, title-like layout (this slide only)
+<!-- _paginate: false -->        # hide page number (this slide only)
+<!-- _backgroundColor: #000 -->  # override background (this slide only)
+<!-- backgroundColor: #1a1a2e --> # set for this slide AND subsequent
+<!-- header: "Section 2" -->     # persistent header
+<!-- footer: "Conf 2026" -->     # persistent footer
+```
+
+### Images
+
+```markdown
+![w:400](figure.png)              # fixed width
+![h:300](figure.png)              # fixed height
+![bg](image.jpg)                  # full background
+![bg right:40%](image.jpg)        # split layout, image right 40%
+![bg left:35%](image.jpg)         # split layout, image left 35%
+![bg contain](image.jpg)          # fit without cropping
+![bg brightness:0.3](image.jpg)   # darkened
+```
+
+### Math
+
+```markdown
+Inline: $E = mc^2$
+
+Block:
+$$
+\mathcal{L} = \sum_i \ell(f(x_i), y_i) + \lambda \|w\|^2
+$$
+```
+
+**Critical pitfall — math inside HTML containers**: Marp's MathJax/KaTeX plugin is a markdown-it tokenizer plugin. It can only render math that markdown-it actually tokenizes. Per CommonMark, content inside a **single-line** HTML block tag is treated as literal text and never re-parsed as Markdown, so the `$...$` never reaches the math plugin and prints as raw dollar signs in the PDF.
+
+This fails silently — there is no warning, just literal `$` characters in the output. When you use layout components from the Inline Component Library (`<div class="cols">`, `<div class="card">`, two- / three-column grids, metric cards), you MUST use one of these patterns:
+
+```html
+<!-- ❌ BROKEN: math on same line as the <div> tag — will NOT render -->
+<div class="card"><strong>$\max_\ell(\tau - t_\ell) \le S_{\max}$</strong></div>
+
+<!-- ✅ FIX A: blank lines inside <div> force markdown-it to re-parse -->
+<div class="card">
+
+**$\max_\ell(\tau - t_\ell) \le S_{\max}$**
+
+</div>
+
+<!-- ✅ FIX B: put block math outside the container; keep only non-math content in the grid -->
+<div class="card">
+<div class="label">Invariant</div>
+</div>
+
+$$\max_\ell(\tau - t_\ell) \le S_{\max}$$
+```
+
+Rule: **whenever a slide has both a `<div>`-based layout and LaTeX math, write the math on its own line with a blank line separating it from the surrounding HTML tags.** Or write the whole slide in pure Markdown without grid containers — inline `$...$` and block `$$...$$` always render correctly in plain Markdown context.
+
+Short exponents like `K=10⁻³` can be written with Unicode superscripts as a last resort in tight layouts, but lose LaTeX fidelity — only acceptable for trivial cases.
+
+## Theme System
+
+### Dark Theme (Conference / Invited Talks)
+
+```yaml
+style: |
+  @import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;600;700&family=JetBrains+Mono:wght@400&display=swap');
+  :root {
+    --accent: #60a5fa;
+    --dark: #0f172a;
+    --card: #1e293b;
+    --border: #334155;
+    --body: #94a3b8;
+    --label: #64748b;
+    --muted: #475569;
+    --light: #f1f5f9;
+    --green: #4ade80;
+    --red: #f87171;
+    --yellow: #fbbf24;
+  }
+  section {
+    background: var(--dark);
+    color: var(--light);
+    font-family: 'Inter', sans-serif;
+    font-weight: 300;
+    padding: 48px 64px;
+  }
+  section.lead {
+    display: flex;
+    flex-direction: column;
+    justify-content: center;
+    text-align: center;
+  }
+  h1 { font-weight: 700; font-size: 2.2em; color: var(--light); margin-bottom: 0.3em; line-height: 1.2; }
+  h2 { font-weight: 300; font-size: 1.3em; color: var(--body); margin-top: 0; }
+  h3 { font-weight: 600; font-size: 0.75em; color: var(--label); text-transform: uppercase; letter-spacing: 0.1em; }
+  p, li { color: var(--body); line-height: 1.6; font-size: 1em; }
+  strong { color: var(--light); font-weight: 600; }
+  em { color: var(--accent); font-style: normal; }
+  code { font-family: 'JetBrains Mono', monospace; font-size: 0.85em; background: var(--card); padding: 2px 6px; border-radius: 4px; }
+  pre { background: var(--card); border: 1px solid var(--border); border-radius: 8px; padding: 16px; }
+  table { width: 100%; border-collapse: collapse; font-size: 0.85em; }
+  th { color: var(--label); font-weight: 600; text-transform: uppercase; font-size: 0.75em; letter-spacing: 0.05em; border-bottom: 1px solid var(--border); padding: 8px 12px; text-align: left; }
+  td { color: var(--body); border-bottom: 1px solid var(--border); padding: 8px 12px; }
+  a { color: var(--accent); text-decoration: none; }
+  blockquote { border-left: 3px solid var(--accent); padding-left: 16px; color: var(--muted); font-style: italic; }
+  footer { color: var(--muted); font-size: 0.6em; }
+```
+
+### Light Theme (Lab Meetings / Classrooms / Print)
+
+```yaml
+style: |
+  @import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;600;700&family=JetBrains+Mono:wght@400&display=swap');
+  :root {
+    --accent: #2563eb;
+    --dark: #f8fafc;
+    --card: #ffffff;
+    --border: #e2e8f0;
+    --body: #475569;
+    --label: #64748b;
+    --muted: #94a3b8;
+    --light: #0f172a;
+    --green: #16a34a;
+    --red: #dc2626;
+    --yellow: #ca8a04;
+  }
+  section {
+    background: var(--dark);
+    color: var(--light);
+    font-family: 'Inter', sans-serif;
+    font-weight: 300;
+    padding: 48px 64px;
+  }
+  section.lead {
+    display: flex;
+    flex-direction: column;
+    justify-content: center;
+    text-align: center;
+  }
+  h1 { font-weight: 700; font-size: 2.2em; color: var(--light); margin-bottom: 0.3em; line-height: 1.2; }
+  h2 { font-weight: 300; font-size: 1.3em; color: var(--body); margin-top: 0; }
+  h3 { font-weight: 600; font-size: 0.75em; color: var(--label); text-transform: uppercase; letter-spacing: 0.1em; }
+  p, li { color: var(--body); line-height: 1.6; font-size: 1em; }
+  strong { color: var(--light); font-weight: 600; }
+  em { color: var(--accent); font-style: normal; }
+  code { font-family: 'JetBrains Mono', monospace; font-size: 0.85em; background: var(--card); padding: 2px 6px; border-radius: 4px; border: 1px solid var(--border); }
+  pre { background: var(--card); border: 1px solid var(--border); border-radius: 8px; padding: 16px; }
+  table { width: 100%; border-collapse: collapse; font-size: 0.85em; }
+  th { color: var(--label); font-weight: 600; text-transform: uppercase; font-size: 0.75em; letter-spacing: 0.05em; border-bottom: 2px solid var(--border); padding: 8px 12px; text-align: left; }
+  td { color: var(--body); border-bottom: 1px solid var(--border); padding: 8px 12px; }
+  a { color: var(--accent); text-decoration: none; }
+  blockquote { border-left: 3px solid var(--accent); padding-left: 16px; color: var(--muted); font-style: italic; }
+  footer { color: var(--label); font-size: 0.6em; }
+```
+
+### Recommended Font Pairings for Research
+
+| Heading / Body | Best For | Notes |
+|----------------|----------|-------|
+| Inter 700 / Inter 300 | General research talks | Clean, highly legible, safe default |
+| Outfit 800 / Raleway 200 | Data-heavy dashboards | High contrast weight difference |
+| DM Serif Display / DM Sans 300 | Humanities, social science | Warmer, editorial feel |
+| Space Grotesk 700 / IBM Plex Mono 300 | CS/Systems talks | Technical, monospace body for code-heavy content |
+| Plus Jakarta Sans 800 / Plus Jakarta Sans 200 | Internal team presentations | Friendly, modern |
+
+## Slide Templates
+
+### Title slide
+
+```markdown
+<!-- _class: lead -->
+<!-- _paginate: false -->
+
+# Paper or Talk Title Here
+## Subtitle or Key Finding in One Line
+
+**Presenter Name**, Co-author, Co-author
+*Affiliation — Conference / Venue, Date*
+```
+
+### Section divider
+
+```markdown
+<!-- _class: lead -->
+<!-- _paginate: false -->
+
+# Methodology
+```
+
+### Assertion-Evidence content slide (default)
+
+```markdown
+# LEGO-xtal generated 1,741 new sp² allotropes from 25 starting structures
+
+![w:700](./figures/energy_distribution.png)
+
+**A ~70× expansion** of the known low-energy sp² carbon space, achieved without a single extra DFT calculation during generation.
+```
+
+### Two-column comparison
+
+```markdown
+# Pre-relaxation cuts optimization time by 10× versus pure energy-based search
+
+<div style="display: flex; gap: 40px;">
+<div style="flex: 1;">
+
+### Without pre-relaxation
+- Random init → MACE optimization
+- ~120 min per 1k samples
+- Many stuck in bad minima
+
+</div>
+<div style="flex: 1;">
+
+### With SO(3) pre-relaxation
+- Descriptor-guided warm start
+- ~9.5 min per 1k samples
+- Higher fraction reach sp² geometry
+
+</div>
+</div>
+```
+
+### Data table slide
+
+```markdown
+# Our model outperforms all baselines on three metrics
+
+| Method | Accuracy | Latency (ms) | Memory (GB) |
+|--------|----------|--------------|-------------|
+| Baseline A | 78.2% | 120 | 4.2 |
+| Baseline B | 81.5% | 95 | 6.1 |
+| **Ours** | **86.3%** | **72** | **3.8** |
+
+**Bold = best in column.** Averaged over 5 runs, all std < 0.3%.
+```
+
+### Equation slide
+
+```markdown
+# Our training objective combines supervised and contrastive losses
+
+$$
+\mathcal{L} = \underbrace{\mathcal{L}_{\text{CE}}(f(x), y)}_{\text{supervised}} + \lambda \underbrace{\mathcal{L}_{\text{CL}}(z_i, z_j)}_{\text{contrastive}}
+$$
+
+- $\lambda = 0.1$ chosen by validation
+- $z_i, z_j$: augmented views of same input
+```
+
+### Thank you / questions
+
+```markdown
+<!-- _class: lead -->
+<!-- _paginate: false -->
+
+# Thank You
+
+**Questions?**
+
+your.email@university.edu
+Paper: arxiv.org/abs/xxxx.xxxxx
+Code: github.com/yourname/project
+```
+
+## Inline Component Library
+
+### Metric cards
+
+```html
+<div style="display: flex; gap: 24px; margin-top: 24px;">
+  <div style="flex: 1; background: var(--card); border: 1px solid var(--border); border-top: 3px solid var(--accent); border-radius: 8px; padding: 20px;">
+    <div style="color: var(--label); font-size: 0.7em; text-transform: uppercase; letter-spacing: 0.1em;">New structures</div>
+    <div style="font-size: 2.2em; font-weight: 700; color: var(--light); margin: 4px 0;">1,741</div>
+    <div style="color: var(--green); font-size: 0.8em;">70× vs training</div>
+  </div>
+</div>
+```
+
+### Simple bar chart (inline SVG)
+
+```html
+<svg viewBox="0 0 500 200" style="width: 100%; max-width: 600px; margin: 20px auto; display: block;">
+  <line x1="60" y1="170" x2="480" y2="170" stroke="var(--border)" stroke-width="1"/>
+  <rect x="80" y="90" width="60" height="80" fill="var(--muted)" rx="4"/>
+  <rect x="180" y="60" width="60" height="110" fill="var(--muted)" rx="4"/>
+  <rect x="280" y="30" width="60" height="140" fill="var(--accent)" rx="4"/>
+  <text x="110" y="190" fill="var(--label)" font-size="12" text-anchor="middle">Baseline A</text>
+  <text x="210" y="190" fill="var(--label)" font-size="12" text-anchor="middle">Baseline B</text>
+  <text x="310" y="190" fill="var(--light)" font-size="12" text-anchor="middle" font-weight="600">Ours</text>
+  <text x="110" y="82" fill="var(--body)" font-size="12" text-anchor="middle">78.2%</text>
+  <text x="210" y="52" fill="var(--body)" font-size="12" text-anchor="middle">81.5%</text>
+  <text x="310" y="22" fill="var(--accent)" font-size="13" text-anchor="middle" font-weight="600">86.3%</text>
+</svg>
+```
+
+## Common Failure Modes
+
+| Symptom | Root cause | Fix |
+|---------|-----------|-----|
+| Audience asks "what was the point?" after talk | Phase 1 was skipped; no clear thesis | Return to Phase 1 |
+| Slides look busy and cramped | Phase 3 violated one-idea limits | Split overloaded slides |
+| Listener got lost in the middle | Missing transitions; assertion chain has gaps | Re-read titles in order |
+| Figures illegible from back row | Used publication figures directly | Re-export at slide sizes using `scientific-visualization` |
+| Content overflows and gets clipped | Marp silent-clipping | Visual preview every slide |
+| Polish consumed all the time | Started Phase 4 before content stable | No visual work until content approved |
+| Math renders as literal `$...$` in PDF | `$...$` is inside a single-line HTML block tag (e.g., `<div class="card">...$x$...</div>`), so markdown-it never tokenizes it | Add blank lines inside the `<div>` around the math, OR move block `$$...$$` outside the container. See Math section for the canonical fix. |
+
+## Export Reference
+
+```bash
+# Live preview during authoring
+npx @marp-team/marp-cli slides.md --watch --html --allow-local-files
+
+# Final HTML
+npx @marp-team/marp-cli slides.md --html --allow-local-files
+
+# PDF backup — ALWAYS produce this
+npx @marp-team/marp-cli slides.md --pdf --allow-local-files
+
+# PPTX (only if editing further in PowerPoint)
+npx @marp-team/marp-cli slides.md --pptx --allow-local-files
+```
+
+## Integration with Other Skills and Tools
+
+| Task | Combine with |
+|------|-------------|
+| Publication-quality figures | `scientific-visualization` → PNG/SVG → embed |
+| Custom low-level plots | `matplotlib` or `seaborn` → PNG/SVG → embed |
+| Diagrams and schematics | `scientific-schematics` → SVG → embed |
+| Convert paper draft → talk | `convert-document` tool on PDF/DOCX → extract assertions in Phase 1 |
+| Fresh data-driven numbers | `data-analyze` tool → feed results into Phase 3 |
+| Related-work / references | `literature-search` tool → populate References backup slide; also used as quick tier-2 context scan in Context Gate |
+| Search workspace for prior work | `artifact-search` on `papers`/`notes` during Context Gate (tier 1) |
+| Paper knowledge base lookups | `wiki_search` / `wiki_get` / `wiki_coverage` / `wiki_neighbors` / `wiki_source` during Context Gate (tier 1) |
+| Long-lived user preferences (venues, co-authors, style) | Read `.research-pilot/memory/MEMORY.md` + linked files during Context Gate (tier 1) |
+| Online fill-ins (venue CFP, keynote examples) | `web_search` / `web_fetch` as tier-3 fallback only |
+| Persist storyline and final deck | `artifact-create` with `type='note'` (Phase 1) and `type='tool-output'` (Phase 4) |
+| Sister skill for lectures | `teaching-marp-slides` — use for classroom/course material |
+
+---
+
+## Final Reminder
+
+Slide quality is set in Phase 1 (storyline) and by the user's own dry run after delivery. **A deck with a weak thesis and beautiful visuals loses to a deck with a sharp thesis and plain visuals — every time.** In Revise Mode, respect the user's existing choices: change only what's requested or clearly broken.