Weekly Research Slides
An Agent Skill for research updates. The deck is a delta on the project's
persistent scientific state, and it is a visual argument, not a bullet dump.
The default deliverable is a template-driven LaTeX Beamer PDF compiled from
structured source; an editable .pptx backend is available with
--renderer pptx when the user needs native editing.
The one idea
Track changes in methods, evidence, claims, diagnostics, and uncertainty
across weeks, then turn those changes into a visual scientific argument.
Workflow
Gather state. Find research_state.yaml (persistent project memory) and
any previous deck/state. If there is a previous state, compute the delta:
wrs diff --prev research_state_week5.yaml --curr research_state.yaml \
--question "<this week's question>" --output weekly_delta.yaml
If the user already provides weekly_delta.yaml, use it directly.
Pick the stage (survey, hypothesis-formation, method-development,
diagnostic, refinement, mature-comparison) and plan the argument:
wrs plan --state research_state.yaml --delta weekly_delta.yaml \
--stage diagnostic --output storyboard.yaml
Author storyboard.yaml -> slide_spec.yaml. One intellectual message
per slide, question/claim titles, visual explanation, progressive disclosure.
Never invent results. Never strengthen a claim beyond its evidence. Keep
measurement, observation, interpretation, and claim separate.
Build, QA, render.
wrs build --input slide_spec.yaml --output deck.pdf --render-pages
wrs qa --input deck.pdf --spec slide_spec.yaml --delta weekly_delta.yaml
wrs render --input deck.pdf --output rendered/ # page PNGs + contact sheet
The build renders semantic LaTeX through templates/academic-beamer/,
compiles with pdflatex (or lualatex for non-Latin-1 content), writes
presentation.pdf and handout.pdf, and hard-fails on compile errors,
overfull boxes, missing figures/citations, and undefined references. The
generated .tex is never patched.
For the legacy editable PowerPoint backend:
wrs build --input slide_spec.yaml --output deck.pptx --renderer pptx \
--motion motion_spec.yaml --preview preview/
wrs qa --input deck.pptx --spec slide_spec.yaml
Fix the source and rebuild until scientific QA, compile/geometry QA, and
visual review pass. Do not patch the generated PDF or PPTX.
Run the editorial critique loop to sharpen the deck:
wrs critique --input slide_spec.yaml --output revised.yaml \
--renderer beamer --deck out.pdf --qa-dir qa
It runs a content critic (deletion-first, moves prose to speaker notes), a
rendered-page visual critic (PDF pages via pdftoppm), and a deck critic,
revising the source and rebuilding. Cycle 1 is deletion-only; at most three
cycles. See references/editorial-critique.md.
Hard rules
- Delta-first: for a mature project open with "What changed this week?", not the
problem definition.
- Adapt the skeleton to the stage; do not force every section.
- End at limitations / open questions. Never auto-add Thank You, Q&A, or
generic next steps.
MEASUREMENT != OBSERVATION != INTERPRETATION != CLAIM != HYPOTHESIS.- Every diagnostic states which claim it tests and what it cannot conclude.
- Object permanence: reuse the same semantic object ids and positions.
- The Beamer template owns presentation (fonts, margins, footer, blocks,
citations); emit semantic macros only, never coordinates or colours. The
feature-space archetype is the one exception: cx/cy are semantic and
become tikz coordinates.
- The PPTX backend uses native PowerPoint objects only; the user must be able
to edit the result. Beamer
.tex is generated, compiled and reproducible.
- Source files are the truth; never patch a generated PDF or PPTX.
Content standard (required)
When present or explain anything, Our presentation must follow a very coherent structure that answer sequentially these question: Why we need to do this/The motivation? What are we going to do after having the requirement? Then explain what we do. You must explain very clear on what we are going to do, then present equation or proposition, theorem when we need clear formal formula to avoid vague, excessive wording. Then present experiment to support our claim if we had. The presentation must be very clear, concise, precise and connected as a complete, convincing story flow throughout the whole paper and each section, each subsection should have their own complete, convincing flow that become a perfectly fit part in the whole complete story flow of the paper. Every formula must be written in clear and easiest way to understand, all notation must be explained clearly before use. The presentation quality must be high, oral-standard, human-like with zero AI slop paragraph that throw to reader a bunch of words without truly saying anything meaningful. The complex mathematical theorem we introduce must be state clearly the message it is trying to deliver, no vague terms or jargon.
Method explainer videos
When a method's mechanism is hard to understand statically — a representation
changes through time, an algorithm iterates, or a multi-stage process is the
point — use the bundled research-method-video sub-skill. It turns the same
scientific understanding into a short 3Blue1Brown-style Manim explainer whose
objects persist and transform, plus a keyframe manifest for slides.
research_state / method_model.yaml
| \
v v
slide_spec.yaml scene_spec.yaml
| |
v v
editable PPTX Manim MP4 + keyframes
Decide first:
- STATIC SLIDES SUFFICIENT — movement adds no explanatory value.
- VIDEO EXPLAINER HELPFUL — temporal dynamics, iteration, geometry, or
multi-stage structure carry the argument.
Narration is written before animation and is a first-class artifact: the
script sets the pacing (silent mode), and the same transcript produces subtitles
(SRT/VTT) and slide speaker notes. See
skills/research-method-video/references/narration-writing.md.
Do not generate a video for every method. See
skills/research-method-video/SKILL.md.
Scientific diagram backends
Route the visual before drawing it; the decision is recorded, never hidden:
would motion materially help? -> Manim
is it a quantitative data plot? -> Python / PGFPlots
simple, conceptual, math-heavy? -> TikZ (default)
large, editable, or a
reconstruction / style transfer? -> Draw.io
TikZ figures are generated from the semantic figure spec (or the Figure IR from
the figure subsystem), compiled natively inside Beamer, inherit the theme
palette and math typography, support progressive overlays, and export
standalone for paper reuse. Generated .tex is inspectable and editable.
wrs route --input figure_spec.yaml [--json]
wrs tikz --input figure_spec.yaml --output figure.tex --standalone out/
wrs tikz:qa --input figure_spec.yaml --output-dir qa/figure
Compiling is not proof a figure looks good: tikz:qa compiles, renders, and
reports actionable defects (reroute_edge, increase_figure_scale,
reduce_node_text, route_to_drawio, ...). See
references/diagram-routing.md and references/tikz-qa.md.
Scientific method figures
Draw.io remains the canonical editable backend for large architecture figures,
style extraction and reconstruction. When the deliverable is such a paper
figure, use the bundled research-method-figure sub-skill. It draws from
the same method model as the slides and the video, keeps .drawio as the
canonical editable source, and exports SVG/PDF/PNG plus native PowerPoint.
METHOD MODEL
|
figure_spec.yaml + style_profile.yaml
|
figure.drawio -> .svg / .pdf / .png -> .pptx
It also supports extracting a reusable style profile from a reference figure and
redrawing different content in that style, and classifying inputs by role
(CONTENT / STRUCTURE / STYLE / LAYOUT / ASSET) so a style reference never leaks
content. See skills/research-method-figure/SKILL.md.
Read next (progressive disclosure)
references/research-story.md — narrative framework.references/research-stages.md — stage -> module selection.references/weekly-delta.md — delta-first behavior and weekly_delta.yaml.references/method-explainer.md — how to explain any method.references/claim-diagnostic.md — claims, diagnostics, epistemic separation.references/visual-grammar.md — shapes, arrows, color semantics.references/slide-archetypes.md — archetype content fields.references/object-continuity.md — semantic ids and Morph-readiness.references/motion-language.md — beat-driven motion and motion_spec.yaml.references/editing-existing-pptx.md — inspect and conservative edits.references/review-checklist.md — scientific and visual QA.references/editorial-critique.md — content / visual / deck critique loop.references/beamer-template.md — the default renderer: template contract,
archetype mapping, compile QA, versioning, engines.references/diagram-routing.md — TikZ / Draw.io / Python / Manim selection.references/tikz-visual-grammar.md — semantic roles, shapes, arrows, overlays.references/tikz-archetypes.md — feature-space, comparison, delta, timeline.references/tikz-qa.md — preflight, rendered-image critique, repair loop.references/academic-slide-style.md — the academic visual language shared by
both renderers (PPTX style variants).skills/research-method-video/SKILL.md — method → Manim explainer video.skills/research-method-figure/SKILL.md — method → editable scientific figure.references/layout-contracts.md — shared layout limits across slides, figures and video.
Commands
npm install
npm run doctor
npm run demo # builds the example as Beamer PDF + handout + page renders (+ legacy PPTX)
npm run build -- --input examples/diagnostic-week/slide_spec.yaml --output out.pdf --render-pages
npm run qa -- --input out.pdf --spec examples/diagnostic-week/slide_spec.yaml
npm run build -- --input examples/diagnostic-week/slide_spec.yaml --output out.pptx --renderer pptx
npm run demo:figures # mixed-renderer deck: TikZ + Draw.io + Beamer native
Local, deterministic, no hosted backend. The default Beamer pipeline needs a
TeX distribution (pdflatex/latexmk) and Poppler's pdftoppm; wrs doctor
reports the state. LibreOffice and rsvg-convert improve legacy PPTX previews
but are not required.
1---2name: weekly-research-slides3description: Turn the week's changes in research methods, evidence, claims, and diagnostics into a concise, visually explanatory research update for a supervisor, PI, mentor, or research group. The default output is a template-driven LaTeX Beamer PDF, with an editable PowerPoint backend when native editing is needed. Use when the user asks to make or update weekly research slides, prepare a lab-meeting deck, compare this week's method against last week's, explain competitor methods visually, build slides that support a research claim with diagnostics, or turn experiment notes into a research update. Not for generic business, marketing, or sales decks.4license: MIT5---67# Weekly Research Slides89An Agent Skill for research updates. The deck is a **delta** on the project's10persistent scientific state, and it is a **visual argument**, not a bullet dump.11The default deliverable is a **template-driven LaTeX Beamer PDF** compiled from12structured source; an editable `.pptx` backend is available with13`--renderer pptx` when the user needs native editing.1415## The one idea1617> Track changes in methods, evidence, claims, diagnostics, and uncertainty18> across weeks, then turn those changes into a visual scientific argument.1920## Workflow21221. **Gather state.** Find `research_state.yaml` (persistent project memory) and23 any previous deck/state. If there is a previous state, compute the delta:2425 ```bash26 wrs diff --prev research_state_week5.yaml --curr research_state.yaml \27 --question "<this week's question>" --output weekly_delta.yaml28 ```2930 If the user already provides `weekly_delta.yaml`, use it directly.31322. **Pick the stage** (`survey`, `hypothesis-formation`, `method-development`,33 `diagnostic`, `refinement`, `mature-comparison`) and plan the argument:3435 ```bash36 wrs plan --state research_state.yaml --delta weekly_delta.yaml \37 --stage diagnostic --output storyboard.yaml38 ```39403. **Author `storyboard.yaml` -> `slide_spec.yaml`.** One intellectual message41 per slide, question/claim titles, visual explanation, progressive disclosure.42 Never invent results. Never strengthen a claim beyond its evidence. Keep43 measurement, observation, interpretation, and claim separate.44454. **Build, QA, render.**4647 ```bash48 wrs build --input slide_spec.yaml --output deck.pdf --render-pages49 wrs qa --input deck.pdf --spec slide_spec.yaml --delta weekly_delta.yaml50 wrs render --input deck.pdf --output rendered/ # page PNGs + contact sheet51 ```5253 The build renders semantic LaTeX through `templates/academic-beamer/`,54 compiles with `pdflatex` (or `lualatex` for non-Latin-1 content), writes55 `presentation.pdf` and `handout.pdf`, and hard-fails on compile errors,56 overfull boxes, missing figures/citations, and undefined references. The57 generated `.tex` is never patched.5859 For the legacy editable PowerPoint backend:6061 ```bash62 wrs build --input slide_spec.yaml --output deck.pptx --renderer pptx \63 --motion motion_spec.yaml --preview preview/64 wrs qa --input deck.pptx --spec slide_spec.yaml65 ```66675. **Fix the source and rebuild** until scientific QA, compile/geometry QA, and68 visual review pass. Do not patch the generated PDF or PPTX.696. **Run the editorial critique loop** to sharpen the deck:7071 ```bash72 wrs critique --input slide_spec.yaml --output revised.yaml \73 --renderer beamer --deck out.pdf --qa-dir qa74 ```7576 It runs a content critic (deletion-first, moves prose to speaker notes), a77 rendered-page visual critic (PDF pages via `pdftoppm`), and a deck critic,78 revising the source and rebuilding. Cycle 1 is deletion-only; at most three79 cycles. See `references/editorial-critique.md`.8081## Hard rules8283- Delta-first: for a mature project open with "What changed this week?", not the84 problem definition.85- Adapt the skeleton to the stage; do not force every section.86- End at limitations / open questions. Never auto-add Thank You, Q&A, or87 generic next steps.88- `MEASUREMENT != OBSERVATION != INTERPRETATION != CLAIM != HYPOTHESIS`.89- Every diagnostic states which claim it tests and what it cannot conclude.90- Object permanence: reuse the same semantic object ids and positions.91- The Beamer template owns presentation (fonts, margins, footer, blocks,92 citations); emit semantic macros only, never coordinates or colours. The93 `feature-space` archetype is the one exception: `cx`/`cy` are semantic and94 become tikz coordinates.95- The PPTX backend uses native PowerPoint objects only; the user must be able96 to edit the result. Beamer `.tex` is generated, compiled and reproducible.97- Source files are the truth; never patch a generated PDF or PPTX.9899## Content standard (required)100101> When present or explain anything, Our presentation must follow a very coherent structure that answer sequentially these question: Why we need to do this/The motivation? What are we going to do after having the requirement? Then explain what we do. You must explain very clear on what we are going to do, then present equation or proposition, theorem when we need clear formal formula to avoid vague, excessive wording. Then present experiment to support our claim if we had. The presentation must be very clear, concise, precise and connected as a complete, convincing story flow throughout the whole paper and each section, each subsection should have their own complete, convincing flow that become a perfectly fit part in the whole complete story flow of the paper. Every formula must be written in clear and easiest way to understand, all notation must be explained clearly before use. The presentation quality must be high, oral-standard, human-like with zero AI slop paragraph that throw to reader a bunch of words without truly saying anything meaningful. The complex mathematical theorem we introduce must be state clearly the message it is trying to deliver, no vague terms or jargon.102103## Method explainer videos104105When a method's mechanism is hard to understand statically — a representation106changes through time, an algorithm iterates, or a multi-stage process is the107point — use the bundled **`research-method-video`** sub-skill. It turns the same108scientific understanding into a short 3Blue1Brown-style Manim explainer whose109objects persist and transform, plus a keyframe manifest for slides.110111```text112research_state / method_model.yaml113 | \114 v v115 slide_spec.yaml scene_spec.yaml116 | |117 v v118 editable PPTX Manim MP4 + keyframes119```120121Decide first:122123- **STATIC SLIDES SUFFICIENT** — movement adds no explanatory value.124- **VIDEO EXPLAINER HELPFUL** — temporal dynamics, iteration, geometry, or125 multi-stage structure carry the argument.126127Narration is written **before** animation and is a first-class artifact: the128script sets the pacing (silent mode), and the same transcript produces subtitles129(SRT/VTT) and slide speaker notes. See130`skills/research-method-video/references/narration-writing.md`.131132Do not generate a video for every method. See133`skills/research-method-video/SKILL.md`.134135## Scientific diagram backends136137Route the visual before drawing it; the decision is recorded, never hidden:138139```text140would motion materially help? -> Manim141is it a quantitative data plot? -> Python / PGFPlots142simple, conceptual, math-heavy? -> TikZ (default)143large, editable, or a144reconstruction / style transfer? -> Draw.io145```146147TikZ figures are generated from the semantic figure spec (or the Figure IR from148the figure subsystem), compiled natively inside Beamer, inherit the theme149palette and math typography, support progressive overlays, and export150standalone for paper reuse. Generated `.tex` is inspectable and editable.151152```bash153wrs route --input figure_spec.yaml [--json]154wrs tikz --input figure_spec.yaml --output figure.tex --standalone out/155wrs tikz:qa --input figure_spec.yaml --output-dir qa/figure156```157158Compiling is not proof a figure looks good: `tikz:qa` compiles, renders, and159reports actionable defects (`reroute_edge`, `increase_figure_scale`,160`reduce_node_text`, `route_to_drawio`, ...). See161`references/diagram-routing.md` and `references/tikz-qa.md`.162163## Scientific method figures164165Draw.io remains the canonical editable backend for large architecture figures,166style extraction and reconstruction. When the deliverable is such a paper167figure, use the bundled **`research-method-figure`** sub-skill. It draws from168the same method model as the slides and the video, keeps `.drawio` as the169canonical editable source, and exports SVG/PDF/PNG plus native PowerPoint.170171```text172METHOD MODEL173 |174 figure_spec.yaml + style_profile.yaml175 |176 figure.drawio -> .svg / .pdf / .png -> .pptx177```178179It also supports extracting a reusable style profile from a reference figure and180redrawing different content in that style, and classifying inputs by role181(CONTENT / STRUCTURE / STYLE / LAYOUT / ASSET) so a style reference never leaks182content. See `skills/research-method-figure/SKILL.md`.183184## Read next (progressive disclosure)185186- `references/research-story.md` — narrative framework.187- `references/research-stages.md` — stage -> module selection.188- `references/weekly-delta.md` — delta-first behavior and `weekly_delta.yaml`.189- `references/method-explainer.md` — how to explain any method.190- `references/claim-diagnostic.md` — claims, diagnostics, epistemic separation.191- `references/visual-grammar.md` — shapes, arrows, color semantics.192- `references/slide-archetypes.md` — archetype content fields.193- `references/object-continuity.md` — semantic ids and Morph-readiness.194- `references/motion-language.md` — beat-driven motion and `motion_spec.yaml`.195- `references/editing-existing-pptx.md` — inspect and conservative edits.196- `references/review-checklist.md` — scientific and visual QA.197- `references/editorial-critique.md` — content / visual / deck critique loop.198- `references/beamer-template.md` — the default renderer: template contract,199 archetype mapping, compile QA, versioning, engines.200- `references/diagram-routing.md` — TikZ / Draw.io / Python / Manim selection.201- `references/tikz-visual-grammar.md` — semantic roles, shapes, arrows, overlays.202- `references/tikz-archetypes.md` — feature-space, comparison, delta, timeline.203- `references/tikz-qa.md` — preflight, rendered-image critique, repair loop.204- `references/academic-slide-style.md` — the academic visual language shared by205 both renderers (PPTX style variants).206- `skills/research-method-video/SKILL.md` — method → Manim explainer video.207- `skills/research-method-figure/SKILL.md` — method → editable scientific figure.208- `references/layout-contracts.md` — shared layout limits across slides, figures and video.209210## Commands211212```bash213npm install214npm run doctor215npm run demo # builds the example as Beamer PDF + handout + page renders (+ legacy PPTX)216npm run build -- --input examples/diagnostic-week/slide_spec.yaml --output out.pdf --render-pages217npm run qa -- --input out.pdf --spec examples/diagnostic-week/slide_spec.yaml218npm run build -- --input examples/diagnostic-week/slide_spec.yaml --output out.pptx --renderer pptx219npm run demo:figures # mixed-renderer deck: TikZ + Draw.io + Beamer native220```221222Local, deterministic, no hosted backend. The default Beamer pipeline needs a223TeX distribution (`pdflatex`/`latexmk`) and Poppler's `pdftoppm`; `wrs doctor`224reports the state. LibreOffice and `rsvg-convert` improve legacy PPTX previews225but are not required.
thanhlamauto