nature-paper2ppt

interface:
  display_name: "Nature Paper to PPT"
  short_description: "Turn scientific papers into polished presentation decks"
  default_prompt: "Use $nature-paper2ppt to turn this scientific paper into a polished, evidence-grounded presentation deck."

name: nature-paper2ppt
version: 2.0.0
description: >
  Declarative manifest for the static/dynamic split. SKILL.md uses this to
  decide which fragments to load for a given paper-to-PPTX request. The main
  axis is the paper type, which selects the presentation narrative arc and the
  default slide structure. Design, figure, and self-review depth live in
  on-demand references so each invocation stays cheap.

always_load:
  # Shared layer — common to the nature-* skills
  - ../nature-shared/core/terminology-ledger.md
  # Skill-local core
  - static/core/principles.md
  - static/core/toolchain.md
  - static/core/workflow.md
  - static/core/output-and-quality.md

axes:
  paper_type:
    detect: |
      Classify the paper before designing slides, then map it onto one of the
      six presentation arcs below. Use the user's stated framing first; fall
      back to inference from the source.
        discovery  — discovery / mechanism papers -> question-to-evidence arc
        methods    — methods / AI / tool / algorithm papers -> problem-to-solution arc
        resource   — resource / dataset / atlas / omics / benchmark papers -> workflow-to-validation arc
        clinical   — clinical / population / intervention studies -> design-to-inference arc
        materials  — materials / chemistry / physics / engineering papers -> property-to-mechanism or design-to-performance arc
        review     — reviews / perspectives / commentaries / meta-analyses -> evidence-map arc
      If the paper is interdisciplinary, pick the arc matching its dominant
      argument, not its field label.
    values:
      discovery:  static/fragments/paper_type/discovery.md
      methods:    static/fragments/paper_type/methods.md
      resource:   static/fragments/paper_type/resource.md
      clinical:   static/fragments/paper_type/clinical.md
      materials:  static/fragments/paper_type/materials.md
      review:     static/fragments/paper_type/review.md
    default: discovery
    multi: false

references:
  on_demand:
    - condition: designing or auditing slide composition, visual rhythm, layout, typography, anti-template, archetypes, on-slide text budget
      path: references/design-and-layout.md
    - condition: selecting, extracting, cropping, and quality-checking figure/table assets
      path: references/figure-assets.md
    - condition: running the self-review/corrective revision loop, severity grading, programmatic PPTX/XML checks, rendered-preview policy, final verification
      path: references/self-review.md

quality_tools:
  pptx_audit_script: scripts/audit_pptx_quality.py
  use_when: after the first PPTX draft and again after revision whenever a real .pptx exists
  purpose: detect shape bounds, text overload, AI-template wording, image crop flags, small evidence images, and alignment near-misses from PPTX XML

# `nature-paper2ppt` Skill

[中文说明](README.md)

`nature-paper2ppt` converts scientific papers, preprints, PDFs, figure legends, or reading notes into Chinese PowerPoint decks for group meetings, journal clubs, paper sharing, and pre-defense preparation.

## What To Use It For

- Reorganize a paper into a 10-16 slide Chinese presentation instead of copying the article structure.
- Extract the research question, key claims, core evidence, limitations, and reusable value.
- Select figures and tables that support the narrative, cropping or splitting dense plates when needed.
- Generate editable `.pptx`, speaker notes, and lightweight QA reports.
- Translate Nature-style evidence narrative into short slide text and live-presentation structure.

## Typical Requests

- "Turn this Nature Communications paper into a 12-slide Chinese group-meeting PPT."
- "Use the abstract and figure legends to make a first paper-presentation draft; keep it concise."
- "Make this machine-learning paper into a deck with clear method, results, and limitations."

## What You Need To Provide

- Paper PDF, DOI, arXiv link, publisher page, abstract plus figure legends, or reading notes.
- Presentation duration, audience background, slide-count range, and whether speaker notes are needed.
- Whether original figures must be preserved and whether cropping or redrawing schematics is allowed.

## Outputs

- Editable PowerPoint file.
- Figure-asset manifest and crop/source notes.
- Slide titles, bullets, takeaways, and speaker notes.
- Package checks for embedded media, slide count, notes, and layout risks.

## Boundaries

- The skill does not turn paper content into generic, untraceable summaries.
- If image quality is poor, the PDF is scanned, or figures cannot be extracted, the limitation and alternative are stated.
- For full translation or paragraph-level reading, use `nature-reader` first.

## Related Skills

- `nature-reader`: build full Chinese-English reading material and a figure source map first.
- `nature-figure`: redraw mechanism or method diagrams for the deck.
- `presentations`: further edit the generated PPTX layout.

# `nature-paper2ppt` 技能

[English](README_EN.md)

`nature-paper2ppt` 用于把科研论文、预印本、PDF、图注或阅读笔记转换为中文 PowerPoint，适合组会、文献汇报、论文分享和答辩前讲稿准备。

## 适合用它做什么

- 将论文重组为 10-16 页中文汇报，而不是照搬原文章节。
- 提取研究问题、关键 claim、核心证据、局限和可复用价值。
- 选择支撑叙事的关键图表，并对密集图版进行裁剪或拆分。
- 生成可编辑 `.pptx`、speaker notes 和轻量 QA 报告。
- 将 Nature 风格证据叙事转化为现场报告的短句和页面结构。

## 典型请求

- “把这篇 Nature Communications 论文做成 12 页中文组会 PPT。”
- “根据摘要和图注先做一版文献汇报，不要太密。”
- “把这篇机器学习论文做成方法、结果、局限都清楚的 PPT。”

## 你需要提供

- 论文 PDF、DOI、arXiv 链接、出版社页面、摘要加图注或阅读笔记。
- 报告时长、听众背景、页数范围和是否需要 speaker notes。
- 是否必须保留原图、是否允许裁剪或重画示意图。

## 产出

- 可编辑 PowerPoint 文件。
- 图表资产清单和裁剪/引用说明。
- 每页标题、要点、takeaway 和 speaker notes。
- 包体检查结果，例如媒体嵌入、页数、备注和布局风险。

## 边界

- 不会把论文内容改写成无法回溯来源的泛泛介绍。
- 图像质量不足、PDF 扫描质量差或原图无法提取时，会说明替代方案。
- 如果任务是全文翻译或逐段阅读，优先使用 `nature-reader`。

## 相关技能

- `nature-reader`：先建立全文中英对照和图表 source map。
- `nature-figure`：重画汇报中的机制图或方法图。
- `presentations`：对生成的 PPTX 做进一步版式编辑。

# Design and layout

## Contents

- [Plan the visual rhythm before authoring](#plan-the-visual-rhythm-before-authoring)
- [On-slide text budget](#on-slide-text-budget)
- [Evidence hierarchy on a slide](#evidence-hierarchy-on-a-slide)
- [Layout adaptation rule](#layout-adaptation-rule)
- [Anti-template design rule](#anti-template-design-rule)
- [Slide archetype defaults](#slide-archetype-defaults)
- [Title writing rule](#title-writing-rule)
- [Visual density rule](#visual-density-rule)
- [Text-fitting implementation rules](#text-fitting-implementation-rules)
- [Alignment and spacing rules](#alignment-and-spacing-rules)
- [Chinese academic expression and de-template rules](#chinese-academic-expression-and-de-template-rules)
- [Style rules](#style-rules)


Open this reference when planning visual rhythm (step 3), writing slide content (step 6), or building the PPTX (step 7). It holds the full composition, layout, typography, and anti-template rules.

## Plan the visual rhythm before authoring

Before creating slides, assign each slide a visual role and avoid repeating the same role too often. Use a rhythm such as: opener / conceptual claim, problem setup, mechanism or workflow, evidence slide, evidence slide with cropped subpanel, comparison or ablation, boundary / limitation, synthesis / discussion.

For each slide, choose one of these composition types:

- `figure-dominant`: figure owns most of the slide; text is a quiet margin note or bottom strip,
- `process-wide`: full-width workflow with small stage labels,
- `claim-led`: one strong sentence with 2-3 supporting fragments, no fake cards,
- `comparison`: table/chart or two evidence blocks with a single conclusion line,
- `discussion`: open layout with a few sharp prompts, not a dense bullet page.

Do not create the whole deck from one generic layout family. If the plan shows repeated `three cards + takeaway` or `figure left + rail right` slides, revise the plan before building.

## On-slide text budget

Write for the slide, not for the manuscript. Most explanation belongs in speaker notes. Use these default limits unless a user-provided template clearly supports more:

- title: one line preferred; two lines allowed only when the slide still has enough vertical space,
- normal slide: 2-3 bullets, each no more than about 18 Chinese characters or 8-10 English words,
- result slide: 1 short interpretation sentence plus at most 2 compact callouts,
- card body: 1 sentence, usually no more than 24 Chinese characters,
- metric label: 1 line whenever possible,
- source label: small and short; do not let source text compete with the figure.

If the point needs more words, split the slide or move the explanation to speaker notes. Do not rely on shrinking text below readable size to make an overfull slide work.

## Evidence hierarchy on a slide

For any result slide, order the visual logic: 1) hero figure or main table crop, 2) narrow interpretation rail or short annotation band, 3) only the minimum labels needed to read the evidence, 4) any deeper explanation moves to speaker notes or the next slide. Do not let the interpretation block become as large or louder than the evidence itself.

## Layout adaptation rule

Do not default to a fixed 50/50 left-right split. Choose the layout from the figure's aspect ratio, density, and role:

- full-width or near-full-width visual when the figure is wide, complex, or the main evidence,
- tall image with a narrow text rail when the figure is vertical or the caption is short,
- top/bottom stack when the figure needs horizontal room or the slide benefits from a short argument above and a visual below,
- asymmetric split such as 70/30, 75/25, or 65/35 when one side dominates,
- compact visual-plus-callout layout when the slide needs only a few annotations,
- a table or figure crop instead of shrinking a dense graphic into a small frame.

Treat equal-weight 1:1 layouts as the exception. In most result slides, one side should clearly dominate. Prefer the smallest text block that still makes the claim legible. For dense figures, crop to the most relevant panels; for sparse slides, do not pad with extra boxes.

## Anti-template design rule

Avoid layouts that look like generic AI-generated slides. Academic restraint does not mean mechanical repetition. Do not overuse: three equal cards with icon/number strips; rows of identical metric pills; the same right-hand interpretation rail on every figure slide; nested rectangles and fake dashboard cards; evenly spaced boxes that ignore the shape of the evidence; generic "problem / solution / impact" grids when the argument has a more specific structure.

Instead, vary the composition based on the evidence: let one figure own the page when it is the evidence; use a single large quote-like claim line only when the slide is conceptual; use small edge annotations or a narrow marginal note instead of big explanatory boxes; use full-width process diagrams for workflows; split a dense figure across two slides instead of adding a crowded rail; place summary text as a quiet bottom strip when the figure is dominant.

Before finalizing, scan the deck at slide-sorter scale. If five or more slides share the same composition, redesign at least some of them so the deck has a natural rhythm.

## Slide archetype defaults

Use these defaults unless the source strongly suggests otherwise:

- Cover slide: one dominant visual or typographic idea, no balanced split, no dashboard-like grid.
- Background/problem slide: short setup text plus one compact context visual or schematic.
- Workflow/method slide: full-width or top-to-bottom process diagram, not two equal text/figure columns.
- Result/evidence slide: one dominant figure or table crop with a narrow interpretation rail; avoid 1:1 layouts unless evidence and explanation truly balance.
- Comparison/table slide: full-width table or split table across slides if it becomes cramped.
- Model/summary slide: a large central model with a brief takeaway strip or short annotation band.
- Conclusion/discussion slide: text-led but open composition, with 2-4 bullets and no unnecessary containers.

## Title writing rule

Use conclusion-style titles whenever possible. A good title states the slide's point, not just its topic. Prefer "PathAgent 主动识别信息不足并补充证据" over labels like "Case Study" or "Figure 3".

## Visual density rule

Do not downscale a dense figure, table, or multi-panel graphic into a tiny slot just to preserve symmetry. If a visual cannot be read at presentation scale, crop it, split it, or give it its own slide. Prefer one legible visual over several cramped ones.

## Text-fitting implementation rules

When authoring with python-pptx or similar tooling:

- Treat automatic text shrinking (`fit_text` or equivalent) as a last resort, not the layout strategy. It can fail silently, behave differently across platforms, or make text too small.
- Prefer writing shorter text, increasing the text box, or splitting the slide.
- Use explicit line breaks for known long phrases, model names, and metric labels.
- Keep text box margins conservative; avoid tiny text boxes with long Chinese-English mixed strings.
- If using auto-fit, still verify the rendered or estimated text size and document the fallback.
- Never accept a slide where text is expected to overflow, be clipped, or require manual resizing by the user.

## Alignment and spacing rules

Build every slide on a small set of visual guides instead of placing objects by eye. At minimum, keep stable guides for:

- title left edge and title baseline,
- main figure left/right edge,
- caption or source strip edge,
- interpretation rail edge,
- bottom note or takeaway band.

Near-miss alignment is worse than intentional asymmetry. If two elements are meant to align, make their left/top edges identical. If they are not meant to align, separate them enough that the difference reads as intentional, not as a few-pixel mistake.

Before final delivery, inspect every result slide for:

- figure edge, caption, and source label sharing a visible relationship,
- source labels attached to the figure rather than floating alone,
- bottom notes and footers using one consistent baseline,
- gutters that are consistent within the slide,
- no orphan text block stranded far from the figure it explains.

Use `scripts/audit_pptx_quality.py` after deck generation to catch shape bounds, repeated near-miss alignment, and text overload. The script is not a substitute for visual review, but any high-severity finding should trigger revision.

## Chinese academic expression and de-template rules

Write Chinese as if the presenter will say it aloud in a serious group meeting. Use source-specific claims and concrete evidence. Avoid slogans, meta-commentary, and common AI summary frames.

Do not use these phrases in slide titles, takeaways, bullets, or speaker notes unless they appear verbatim in the source and are being quoted:

- `一句话总结`
- `最有价值的后续方向`
- `不是……而是……`
- `不只是……更是……`
- `值得注意的是`
- `总的来说`
- `从某种意义上`
- `提供了新的视角`
- `具有重要意义`
- `未来可以进一步探索`

Replace template wording with evidence-bound language:

```text
Weak: 一句话总结：该方法具有重要意义。
Better: 该方法把检索、证据补全和答案生成拆成可审计流程，降低了遗漏关键文献的风险。
```

```text
Weak: 这不是简单的性能提升，而是范式转变。
Better: 消融实验显示，主动检索模块主要提升了长尾问题的可回答率。
```

If a sentence sounds like it could fit any paper, rewrite it until it names the method, dataset, mechanism, figure evidence, or limitation from this paper.

## Style rules

Use a restrained Nature-style academic presentation design: clean white or very light background; dark readable text; one or two muted accent colors; compact but not crowded layouts; figure-first result slides; concise captions; no decorative stock images; no decorative gradients; no exaggerated marketing-style section pages.

Use Chinese suitable for oral academic reporting: avoid rigid translation; avoid long paragraphs; avoid jargon stacking; preserve technical terms where Chinese translation would reduce precision; prefer evidence-based interpretation over vague praise.

Treat each slide like a publication figure page: one dominant idea, one clear evidence hierarchy, and asymmetry when the story needs it.

### Nature-style page composition

- Prefer one hero visual per slide when the evidence is complex or the claim is central.
- Use asymmetric layouts by default when the visual and the text are not equally important.
- Keep gutters real and tight. Use whitespace to separate roles, not to make a balanced grid.
- Use small panel labels (`a`, `b`, `c`) when a slide contains multiple visual subpanels.
- Use direct labels or a shared legend strip when categories repeat across panels.
- Reuse one restrained palette across the slide or slide family; reserve green/red for gains, drops, or directional change.
- If a slide has a schematic and data, let one dominate and the other validate.
- Use dark backgrounds only when the dominant visual is an image plate or benefits from it; keep normal chart slides light.
- Avoid decorative boxes, fake cards, and symmetrical two-column scaffolds unless the content truly calls for them.
- If a figure would become unreadable when scaled down, crop it, split it, or move it to its own slide.

### Typography system

- Build a clear three-level hierarchy: title, body, caption/source. Do not let every text block look like the same font at slightly different sizes.
- Use one Chinese sans-serif family for most copy and one English/number companion font for metrics, abbreviations, model names, DOI, and small metadata.
- Prefer title sizes roughly in the 24-32 pt range, body copy in the 12-16 pt range, and source/caption text in the 7-9 pt range unless the template clearly calls for something else.
- Let titles carry more weight than bullets. Large metrics may stand out but must not overpower the slide title or main figure.
- Keep captions and source labels lighter in color and smaller in size than the main argument text.
- Avoid mixing many font families on one slide. One Chinese family plus one English/numeric companion is the default maximum.

### Figure-text coordination

- Do not let figures look pasted onto the page. Pair them with a clear shared field: a tight frame, a caption edge, an interpretation rail, or a short takeaway strip.
- When a slide has one dominant figure, let the figure own about 55-75% of the slide area and keep explanatory text to a narrow rail or short band.
- Keep captions attached to the figure edge or inside a bottom caption band. Avoid detached caption text floating far from the visual.
- Use 1-3 metric callouts or a short interpretation strip to help read the figure; do not surround the figure with many equal-weight boxes.
- If the source figure is very dense, prefer a cropped hero panel plus one or two callouts over shrinking the entire figure and compensating with long bullets.
- Use text to guide the reading order and interpretation of the figure, not to repeat every panel label in prose.

### Page fullness rule

- Slides should feel complete rather than empty. Most slides should have a stable top anchor, a dominant middle block, and a bottom anchor such as a takeaway strip, source strip, or conclusion line.
- Add fullness through evidence-supporting elements: metric chips, compact interpretation bands, short source strips, or a narrow comparison block.
- Avoid large unstructured blank areas caused by tiny figures, short bullets marooned in one corner, or captions far from the visual.
- If a slide still feels sparse after placing the main claim and figure, add one concise support layer before adding more bullets.
- Do not fill space with decoration alone. Any added block should clarify hierarchy, guide reading order, or improve figure readability.

### Slide archetype recipes

- Hero figure result slide: 60-75% visual area, 20-30% interpretation rail, and a short takeaway band.
- Workflow slide: one full-width or near-full-width process visual plus a compact annotation strip, not two equal columns.
- Comparison slide: one chart or table block plus a slim metric or conclusion rail; split into two slides if the table becomes cramped.
- Text-led synthesis slide: 2-4 strong bullets or 3 compact claim cards, plus one summary sentence or discussion strip at the bottom.
- Cover slide: one dominant visual or typographic block, a small metadata band, and no dashboard-like grid of equally weighted mini-elements.

# Figure and table assets

Open this reference for steps 4-5: selecting figures as evidence, extracting and preparing assets, and the figure-crop self-check.

## Step 4 detail — select figures as evidence, not decoration

Inspect the source for: graphical abstracts or summary models; study design and workflow diagrams; central result figures; microscopy or imaging panels; heatmaps, dimensionality reduction, networks, maps, or spatial plots; survival curves, forest plots, calibration curves, or statistical result plots; materials characterization and performance plots; model architecture, benchmark, ablation, or error analysis figures; key tables; validation or control figures.

Prioritize figures that carry the paper's argument:

1. design/workflow,
2. main evidence,
3. validation or robustness,
4. mechanism/model/synthesis,
5. practical or conceptual implication.

Prefer a few readable key panels over many unreadable full figures.

## Step 5 detail — extract and prepare figure assets

When the source contains usable figures:

- extract original images from the PDF or source package when possible, but only for selected figures,
- render high-resolution page images only for pages containing selected figures or tables,
- crop relevant panels when full figures are too dense,
- keep original data visuals unchanged,
- save images under `output/assets/figures/`,
- use clear filenames such as `fig1_workflow.png`, `fig2b_main_result.png`, or `fig4ef_validation.png`,
- record source page, figure number, panel, crop status, and intended slide in `output/asset_manifest.md`.

For a standard 10-14 slide journal-club deck, usually select 4-8 figure/table assets. Add more only when they directly support distinct evidence slides.

For tables and simple quantitative comparisons, prefer editable PPT-native tables/charts when values are explicit in the paper text or table. Use table screenshots only when recreating the table would risk transcription errors or when layout/formatting itself is the evidence.

If extraction fails, use the best available fallback:

- rendered page screenshot with careful crop,
- recreated editable table only when values are explicitly available,
- clearly labeled placeholder only when the visual is unavailable.

## Figure crop self-check before slide insertion

Before building the final PPTX, create a quick contact sheet or inspect selected crops directly. This is a cheap way to catch the most common deck defects before they become slide defects.

Check every selected figure/table asset for:

- clipped titles, axis labels, legends, panel letters, or source figure labels,
- irrelevant surrounding paper text or captions included in the crop,
- too little margin around the crop, especially at the top and left edges,
- unreadable small text after the planned slide scaling,
- dense multi-panel figures that should be split into separate slides or cropped to key panels,
- low-resolution or blurry rendering.

Revise the crop before placing it in the PPTX when any scientific context is cut off. A figure crop that loses a title, y-axis label, legend, or panel label is a defect, not an acceptable tradeoff.

## Crop QA hard gate

Treat figure crops as evidence, not decoration. A crop is not acceptable until it passes all applicable checks below:

- panel letters are present when the slide refers to a panel letter,
- x/y axes, axis titles, tick labels, color bars, legends, scale bars, and table headers are preserved when they are needed to read the evidence,
- method labels, condition names, group labels, and sample labels remain visible,
- the crop has a small safety margin around the scientific content rather than cutting exactly at the ink boundary,
- the planned slide placement still leaves the figure readable without asking the audience to zoom,
- no caption, source note, or callout covers original scientific labels.

If any item fails, fix the asset before authoring the slide. Use one of these repairs:

1. expand the crop rectangle,
2. split the source figure across two slides,
3. use a full-width hero figure slide,
4. recreate a simple table/chart natively when values are explicit,
5. replace the crop with a higher-resolution source image.

Record the pass/fail result in `output/asset_manifest.md`. Use compact fields such as:

```text
asset: fig2b_main_result.png
source: Fig. 2b, p. 5
slide: 7
method: pdf page render at 300 dpi, manual crop
crop_qa: pass
preserved: panel label, axes, legend, colorbar
notes: split from Fig. 2 because full figure was unreadable at slide scale
```

If the crop is a deliberate partial crop, state exactly what was omitted and why it is not needed for the slide's claim.

# Self-review and verification

## Contents

- [The loop](#the-loop)
- [Self-review checklist](#self-review-checklist)
- [Severity rules](#severity-rules)
- [Programmatic checks when using python-pptx](#programmatic-checks-when-using-python-pptx)
- [Rendered preview policy](#rendered-preview-policy)
- [Step 9 — final verification](#step-9-final-verification)


Open this reference for step 8 (self-review/corrective revision loop) and step 9 (final verification).

## The loop

After creating the first PPTX draft, run at least one explicit self-review pass before declaring the deck final. Treat this as a defect-finding step, not a confirmation step.

1. Inspect the generated PPTX and extracted assets.
2. Write a short defect list with severity (`high`, `medium`, `low`) and slide numbers.
3. Correct every high-severity issue and every medium-severity issue that can be fixed without expanding the task substantially.
4. Regenerate the PPTX after edits.
5. Re-run verification and update `output/qa_report.md` with what was checked, what was fixed, and what remains.

## Self-review checklist

Check content and structure:

- slide order follows the paper's argument, not merely the paper section order,
- each slide has one dominant claim,
- slide titles are conclusion-style where possible,
- no invented numbers, mechanisms, datasets, claims, or unsupported implications,
- result slides include source labels and do not remove original scientific labels,
- speaker notes exist when planned and are useful for oral explanation.

Check visual and layout quality:

- no cropped-off figure titles, axes, legends, panel labels, or important annotations,
- no source figure is squeezed so far that the evidence becomes unreadable,
- dense figures are split or cropped rather than placed as tiny full-figure screenshots,
- text boxes, figures, captions, source labels, and takeaway bands do not overlap,
- no text visually exceeds or is likely to exceed its text box; text overflow is a delivery-blocking defect,
- all shapes stay inside slide bounds,
- text density is reasonable; move excess explanation into speaker notes or split the slide,
- layout rhythm feels intentional rather than generated from one repeated card/rail template,
- no slide uses equal cards or metric chips merely to fill space,
- cards, metrics, and captions have consistent spacing and alignment,
- font choices are Office-safe; avoid relying on a font that is unavailable in the environment for text fitting.

## Severity rules

Use `high` for defects that can mislead the audience or make the deck look broken:

- clipped scientific evidence such as axes, legends, panel labels, table rows, figure titles, or method labels,
- unreadable main evidence on a key result slide,
- overlapping text/figures, text cut off by its box, or text extending beyond a visible boundary,
- wrong slide order or missing central evidence,
- fabricated or unsupported quantitative statements.

Use `medium` for defects that reduce professionalism or comprehension:

- overly dense slides,
- rigid AI-looking layouts, especially repeated equal cards, repeated right-side rails, or decorative metric rows,
- weak crop margins,
- figure captions detached from the visual,
- excessive repeated layouts,
- missing or unhelpful speaker notes,
- ambiguous source attribution.

Use `low` for cosmetic issues that do not affect comprehension:

- minor alignment imperfections,
- palette or typography refinements,
- optional split of a readable but dense figure.

## Programmatic checks when using python-pptx

When generating with python-pptx, perform a lightweight audit in code after the first draft and again after revision. Run the bundled audit script whenever a real PPTX exists:

```bash
python skills/nature-paper2ppt/scripts/audit_pptx_quality.py \
  output/final_presentation_cn.pptx \
  --report output/pptx_audit.md \
  --fail-on high
```

If the script reports high-severity findings, treat the deck as not ready. Fix the deck, regenerate, and run the script again. Copy the final audit summary into `output/qa_report.md`.

The script checks common structural and language issues directly from PPTX XML:

- shapes outside the slide canvas,
- suspicious image crop settings,
- main evidence images that are too small for presentation use,
- repeated near-miss alignment between objects,
- text-heavy shapes likely to overflow,
- AI-template phrases such as `一句话总结`, `最有价值的后续方向`, and `不是……而是……`,
- slide count, media count, and notes count.

Also perform these checks in code or manually when the generation stack allows it:

- reopen the PPTX with `Presentation(output_path)`,
- count slides and embedded media,
- count non-empty notes slides if notes were planned,
- check every shape's left/top/right/bottom stays within the slide canvas,
- flag text-heavy slides by character count and number of text boxes,
- flag any text box whose estimated text length is too large for its width/height, especially mixed Chinese-English strings,
- flag long unbroken tokens or labels that may overflow narrow boxes,
- count repeated layout patterns and flag decks that reuse the same composition too often,
- flag images whose displayed size is too small for their role,
- scan for placeholder text such as `lorem`, `xxxx`, or accidental unreplaced labels.

These checks cannot prove visual perfection, but they reliably catch many failures and should trigger a manual/self-review pass.

## Rendered preview policy

Render slide previews when a reliable headless renderer is readily available. If rendered previews are available, inspect them for: missing images; distorted or low-resolution figures; unreadable panels; text overflow; overlapping captions, bullets, and figures; excessive bullet density; wrong slide order; missing source labels; missing or unhelpful speaker notes.

If rendered preview reveals defects, revise and regenerate the PPTX. Do not deliver a deck with obvious visual defects merely because the package validates.

If no reliable renderer is available, still complete the self-review loop using: crop/contact-sheet inspection for selected assets; `audit_pptx_quality.py`; slide-by-slide text and shape inspection; and a clear note in `output/qa_report.md` that rendered preview was unavailable.

## Step 9 — final verification

After revision, perform lightweight verification: reopen the PPTX with the generation library when possible; check slide count; check embedded media count; check speaker notes presence when notes were planned; run `audit_pptx_quality.py`; check obvious shape bounds if tooling supports it; create or inspect a contact sheet from selected extracted assets when figures were cropped.

Do not stop at "PPTX opens" if the self-review found high-severity issues. Correct them first, then verify again. Document any remaining limitation in `output/qa_report.md`.

#!/usr/bin/env python3
"""Lightweight PPTX QA for nature-paper2ppt outputs.

The script intentionally uses only the Python standard library so it can run in
minimal environments. It inspects PPTX XML for common delivery defects; it does
not replace rendered-slide visual review.
"""

from __future__ import annotations

import argparse
import json
import re
import sys
import zipfile
from dataclasses import dataclass, asdict
from pathlib import Path
from typing import Iterable
from xml.etree import ElementTree as ET


EMU_PER_INCH = 914400
EMU_PER_POINT = 12700
DEFAULT_SLIDE_CX = 12192000
DEFAULT_SLIDE_CY = 6858000

NS = {
    "p": "http://schemas.openxmlformats.org/presentationml/2006/main",
    "a": "http://schemas.openxmlformats.org/drawingml/2006/main",
}

AI_PATTERNS = [
    ("一句话总结", re.compile(r"一句话总结")),
    ("最有价值的后续方向", re.compile(r"最有价值的后续方向")),
    ("不是……而是……", re.compile(r"不是.{0,18}而是")),
    ("不只是……更是……", re.compile(r"不只是.{0,18}更是")),
    ("值得注意的是", re.compile(r"值得注意的是")),
    ("总的来说", re.compile(r"总的来说")),
    ("从某种意义上", re.compile(r"从某种意义上")),
    ("提供了新的视角", re.compile(r"提供.{0,8}新的视角")),
    ("具有重要意义", re.compile(r"具有重要意义")),
    ("未来可以进一步探索", re.compile(r"未来可以进一步探索")),
]


@dataclass
class Finding:
    severity: str
    slide: int | None
    code: str
    message: str


@dataclass
class ShapeInfo:
    kind: str
    left: int
    top: int
    width: int
    height: int
    text: str
    cropped: bool = False
    crop_values: dict[str, int] | None = None

    @property
    def right(self) -> int:
        return self.left + self.width

    @property
    def bottom(self) -> int:
        return self.top + self.height

    @property
    def area_fraction(self) -> float:
        return (self.width * self.height) / (DEFAULT_SLIDE_CX * DEFAULT_SLIDE_CY)


def parse_xml(raw: bytes, path: str) -> ET.Element:
    try:
        return ET.fromstring(raw)
    except ET.ParseError as exc:
        raise SystemExit(f"Failed to parse {path}: {exc}") from exc


def local_name(tag: str) -> str:
    return tag.rsplit("}", 1)[-1]


def slide_number_from_path(path: str) -> int:
    match = re.search(r"slide(\d+)\.xml$", path)
    return int(match.group(1)) if match else 0


def get_slide_size(zf: zipfile.ZipFile) -> tuple[int, int]:
    try:
        root = parse_xml(zf.read("ppt/presentation.xml"), "ppt/presentation.xml")
    except KeyError:
        return DEFAULT_SLIDE_CX, DEFAULT_SLIDE_CY
    size = root.find(".//p:sldSz", NS)
    if size is None:
        return DEFAULT_SLIDE_CX, DEFAULT_SLIDE_CY
    return int(size.get("cx", DEFAULT_SLIDE_CX)), int(size.get("cy", DEFAULT_SLIDE_CY))


def text_from_node(node: ET.Element) -> str:
    return "".join(t.text or "" for t in node.findall(".//a:t", NS)).strip()


def shape_bounds(node: ET.Element) -> tuple[int, int, int, int] | None:
    xfrm = node.find(".//a:xfrm", NS)
    if xfrm is None:
        xfrm = node.find(".//p:xfrm", NS)
    if xfrm is None:
        return None
    off = xfrm.find("a:off", NS)
    ext = xfrm.find("a:ext", NS)
    if off is None or ext is None:
        return None
    return (
        int(off.get("x", "0")),
        int(off.get("y", "0")),
        int(ext.get("cx", "0")),
        int(ext.get("cy", "0")),
    )


def crop_info(node: ET.Element) -> tuple[bool, dict[str, int] | None]:
    src_rect = node.find(".//a:srcRect", NS)
    if src_rect is None:
        return False, None
    values = {key: int(src_rect.get(key, "0")) for key in ("l", "r", "t", "b")}
    return any(value != 0 for value in values.values()), values


def extract_shapes(root: ET.Element) -> list[ShapeInfo]:
    shapes: list[ShapeInfo] = []
    for node in root.iter():
        name = local_name(node.tag)
        if name not in {"sp", "pic", "graphicFrame"}:
            continue
        bounds = shape_bounds(node)
        if bounds is None:
            continue
        left, top, width, height = bounds
        text = text_from_node(node)
        cropped, crops = crop_info(node)
        kind = "image" if name == "pic" else "table" if name == "graphicFrame" else "text"
        shapes.append(ShapeInfo(kind, left, top, width, height, text, cropped, crops))
    return shapes


def chars_per_square_inch(text: str, width: int, height: int) -> float:
    if not text or width <= 0 or height <= 0:
        return 0.0
    area = (width / EMU_PER_INCH) * (height / EMU_PER_INCH)
    return len(text) / max(area, 0.01)


def add_bounds_findings(findings: list[Finding], slide_no: int, shapes: list[ShapeInfo], slide_cx: int, slide_cy: int) -> None:
    for shape in shapes:
        if shape.left < 0 or shape.top < 0 or shape.right > slide_cx or shape.bottom > slide_cy:
            findings.append(
                Finding(
                    "high",
                    slide_no,
                    "shape_out_of_bounds",
                    f"{shape.kind} shape extends outside slide bounds",
                )
            )


def add_text_findings(findings: list[Finding], slide_no: int, shapes: list[ShapeInfo]) -> None:
    for shape in shapes:
        if not shape.text:
            continue
        for label, pattern in AI_PATTERNS:
            if pattern.search(shape.text):
                findings.append(
                    Finding(
                        "medium",
                        slide_no,
                        "ai_template_phrase",
                        f"Template-like phrase found: {label}",
                    )
                )
        density = chars_per_square_inch(shape.text, shape.width, shape.height)
        if len(shape.text) >= 60 and density > 80:
            findings.append(
                Finding(
                    "medium",
                    slide_no,
                    "text_overload",
                    f"Text box may overflow or feel dense ({len(shape.text)} chars)",
                )
            )


def add_image_findings(findings: list[Finding], slide_no: int, shapes: list[ShapeInfo], slide_cx: int, slide_cy: int) -> None:
    slide_area = slide_cx * slide_cy
    for shape in shapes:
        if shape.kind != "image":
            continue
        fraction = (shape.width * shape.height) / max(slide_area, 1)
        if shape.cropped:
            crop_sum = sum((shape.crop_values or {}).values())
            severity = "high" if crop_sum >= 25000 else "medium"
            findings.append(
                Finding(
                    severity,
                    slide_no,
                    "image_crop_applied",
                    f"Image has PPT crop settings {shape.crop_values}; confirm axes, legends, panel labels, and scale bars are preserved",
                )
            )
        if fraction < 0.08:
            findings.append(
                Finding(
                    "medium",
                    slide_no,
                    "small_evidence_image",
                    f"Image occupies only {fraction:.1%} of slide area; main evidence may be unreadable",
                )
            )


def near_miss_pairs(values: list[tuple[int, ShapeInfo]], threshold_min: int, threshold_max: int) -> Iterable[tuple[ShapeInfo, ShapeInfo, int]]:
    for index, (value_a, shape_a) in enumerate(values):
        for value_b, shape_b in values[index + 1 :]:
            delta = abs(value_a - value_b)
            if threshold_min <= delta <= threshold_max:
                yield shape_a, shape_b, delta


def add_alignment_findings(findings: list[Finding], slide_no: int, shapes: list[ShapeInfo]) -> None:
    meaningful = [s for s in shapes if s.width > EMU_PER_POINT * 20 and s.height > EMU_PER_POINT * 12]
    min_delta = 2 * EMU_PER_POINT
    max_delta = 8 * EMU_PER_POINT
    emitted = 0
    for axis, values in (
        ("left", [(s.left, s) for s in meaningful]),
        ("top", [(s.top, s) for s in meaningful]),
    ):
        for _, _, delta in near_miss_pairs(values, min_delta, max_delta):
            findings.append(
                Finding(
                    "low",
                    slide_no,
                    "alignment_near_miss",
                    f"Two objects have {axis}-edge near-miss alignment ({delta / EMU_PER_POINT:.1f} pt apart)",
                )
            )
            emitted += 1
            if emitted >= 4:
                return


def audit_pptx(path: Path) -> dict:
    findings: list[Finding] = []
    slide_summaries: list[dict] = []
    with zipfile.ZipFile(path) as zf:
        slide_cx, slide_cy = get_slide_size(zf)
        slide_paths = sorted(
            (name for name in zf.namelist() if re.match(r"ppt/slides/slide\d+\.xml$", name)),
            key=slide_number_from_path,
        )
        media_count = len([name for name in zf.namelist() if name.startswith("ppt/media/")])
        notes_count = len([name for name in zf.namelist() if name.startswith("ppt/notesSlides/notesSlide") and name.endswith(".xml")])
        for slide_path in slide_paths:
            slide_no = slide_number_from_path(slide_path)
            root = parse_xml(zf.read(slide_path), slide_path)
            shapes = extract_shapes(root)
            add_bounds_findings(findings, slide_no, shapes, slide_cx, slide_cy)
            add_text_findings(findings, slide_no, shapes)
            add_image_findings(findings, slide_no, shapes, slide_cx, slide_cy)
            add_alignment_findings(findings, slide_no, shapes)
            slide_summaries.append(
                {
                    "slide": slide_no,
                    "shape_count": len(shapes),
                    "image_count": sum(1 for s in shapes if s.kind == "image"),
                    "text_chars": sum(len(s.text) for s in shapes if s.text),
                }
            )

    counts = {"high": 0, "medium": 0, "low": 0}
    for finding in findings:
        counts[finding.severity] += 1
    return {
        "file": str(path),
        "slide_count": len(slide_summaries),
        "media_count": media_count,
        "notes_count": notes_count,
        "finding_counts": counts,
        "findings": [asdict(finding) for finding in findings],
        "slides": slide_summaries,
    }


def markdown_report(result: dict) -> str:
    lines = [
        "# PPTX Quality Audit",
        "",
        f"- File: `{result['file']}`",
        f"- Slides: {result['slide_count']}",
        f"- Embedded media: {result['media_count']}",
        f"- Notes slides: {result['notes_count']}",
        f"- Findings: high={result['finding_counts']['high']}, medium={result['finding_counts']['medium']}, low={result['finding_counts']['low']}",
        "",
        "## Findings",
        "",
    ]
    if not result["findings"]:
        lines.append("No structural findings detected by the XML audit.")
    else:
        lines.append("| Severity | Slide | Code | Message |")
        lines.append("|---|---:|---|---|")
        for item in result["findings"]:
            slide = "" if item["slide"] is None else str(item["slide"])
            message = item["message"].replace("|", "\\|")
            lines.append(f"| {item['severity']} | {slide} | `{item['code']}` | {message} |")
    lines.extend(
        [
            "",
            "## Scope",
            "",
            "This XML audit checks structural risk signals. It does not verify scientific correctness or replace rendered-slide visual inspection.",
        ]
    )
    return "\n".join(lines) + "\n"


def severity_rank(name: str) -> int:
    return {"none": 99, "low": 1, "medium": 2, "high": 3}[name]


def should_fail(result: dict, fail_on: str) -> bool:
    if fail_on == "none":
        return False
    threshold = severity_rank(fail_on)
    return any(severity_rank(item["severity"]) >= threshold for item in result["findings"])


def parse_args() -> argparse.Namespace:
    parser = argparse.ArgumentParser(description="Audit PPTX structure for nature-paper2ppt quality issues.")
    parser.add_argument("pptx", type=Path)
    parser.add_argument("--report", type=Path, help="Write a Markdown report to this path.")
    parser.add_argument("--json", type=Path, help="Write raw JSON audit data to this path.")
    parser.add_argument("--fail-on", choices=["high", "medium", "low", "none"], default="high")
    return parser.parse_args()


def main() -> int:
    args = parse_args()
    if not args.pptx.exists():
        raise SystemExit(f"PPTX not found: {args.pptx}")
    result = audit_pptx(args.pptx)
    report = markdown_report(result)
    if args.report:
        args.report.parent.mkdir(parents=True, exist_ok=True)
        args.report.write_text(report, encoding="utf-8")
    else:
        print(report)
    if args.json:
        args.json.parent.mkdir(parents=True, exist_ok=True)
        args.json.write_text(json.dumps(result, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
    return 1 if should_fail(result, args.fail_on) else 0


if __name__ == "__main__":
    raise SystemExit(main())

---
name: nature-paper2ppt
description: Build a complete Nature-style Chinese PPTX presentation from a scientific paper, preprint, PDF, article text, figure legends, or reading notes. Use for journal club, group meeting, thesis seminar, paper sharing, conference or defense decks, and Chinese requests such as 论文做PPT、论文汇报、组会PPT、文献汇报、学术汇报、做幻灯片、读书报告PPT. It classifies paper type, builds an evidence-led story, selects key figures, writes Chinese slide content and speaker notes, creates the actual .pptx, and runs corrective QA for complete figure crops, stable alignment, text overflow, and de-templated Chinese academic expression. Also trigger when improving weak paper-to-PPT output with cropped figures, loose alignment, obvious AI-style wording, or heavy manual rework.
---

# Paper-to-PPTX — Router

This skill is split into two layers:

- A **static layer** under `static/` that holds versioned, reusable content fragments (core principles, toolchain policy, the 9-step workflow, output/quality rules, and per-paper-type presentation arcs).
- A **dynamic layer** (this file plus `manifest.yaml`) that detects the paper type and loads only the fragments needed for the current job. Deep design, figure, and self-review material lives in on-demand references.

Do not try to apply the deck-building logic from memory or from this router. Always load fragments from disk as described below.

## Routing protocol

Follow these five steps every time the skill is invoked.

### 1. Load the manifest and the core layer

Read [manifest.yaml](manifest.yaml). It declares the `paper_type` axis, the allowed values, and the file paths each value maps to.

Also read every file listed under `always_load`. These hold the purpose and core principle, the lean operating mode and toolchain policy, the 9-step workflow spine, and the output/quality rules that apply to every deck, plus the shared Terminology Ledger used to keep technical terms consistent across slides.

### 2. Classify the paper type

Decide the `paper_type` value using the manifest's `detect:` hint and the source:

- `discovery` — discovery / mechanism papers (question-to-evidence arc). Default.
- `methods` — methods / AI / tool / algorithm papers (problem-to-solution arc).
- `resource` — resource / dataset / atlas / omics / benchmark papers (workflow-to-validation arc).
- `clinical` — clinical / population / intervention studies (design-to-inference arc).
- `materials` — materials / chemistry / physics / engineering papers (property-to-mechanism / design-to-performance arc).
- `review` — reviews / perspectives / commentaries / meta-analyses (evidence-map arc).

State the detected value in one short line to the user before designing slides, so they can correct you cheaply.

### 3. Load the matching fragment

Read the file mapped for the detected `paper_type`. It gives the presentation arc and how to adapt the default slide structure for this type. Do **not** read every fragment in `static/`.

### 4. Build the deck using the loaded material

Apply the loaded fragments in this priority order:

1. Core principles (`core/principles.md`) — the argument is the spine; lean operating mode; accepted inputs; Chinese-by-default language rule.
2. Toolchain policy and fast path (`core/toolchain.md`) — cross-platform Python-first stack, default fast path.
3. Paper-type arc (the loaded `paper_type` fragment) — narrative order and slide structure for this paper.
4. Workflow (`core/workflow.md`) — run the 9 steps end to end.
5. Output and quality rules (`core/output-and-quality.md`) — deliverables, quality gates, fallbacks.

Build the Terminology Ledger (`../nature-shared/core/terminology-ledger.md`) while reading the source, so model names, gene/protein names, datasets, metrics, and abbreviations stay identical across every slide and speaker note.

The end product is a real `.pptx` deck, not an outline or script. Do not fabricate results, numbers, or figure details.

### 5. Reach for references only when needed

The files under `references/` are deep references, not defaults. Open them on demand per the `references.on_demand` table in the manifest:

- composing/auditing slide layout, visual rhythm, typography, anti-template design, archetypes, on-slide text budget → `references/design-and-layout.md`.
- selecting, extracting, cropping, and quality-checking figure/table assets → `references/figure-assets.md`.
- running the self-review/corrective revision loop, severity grading, programmatic PPTX checks, rendered-preview policy, and final verification → `references/self-review.md`.

When a real PPTX has been generated, run `scripts/audit_pptx_quality.py` unless the file is unavailable. Treat high-severity findings as blockers, revise the deck, then re-run the audit and record the final result in `output/qa_report.md`.

## Why this split

- The static layer is versioned and reviewable. Adding a new paper-type arc is one new fragment plus one manifest line.
- The dynamic layer keeps each invocation cheap: only the arc for this paper enters context up front; heavy design and QA material loads only when that step runs.
- The router itself is short on purpose. Update fragments, not this file, when adding scope.
- This structure mirrors `nature-writing`, `nature-polishing`, and `nature-reader` so shared content lives in `nature-shared/`.

# Output files, citation, and quality rules

## Citation and attribution rules

Include source information:

- title slide: paper title, authors if useful, journal/preprint server, year, DOI if available,
- figure slides: small labels such as `Source: Fig. 2b, Nature, 2024`,
- adapted or redrawn content: label as `整理自` or `改绘自`,
- do not remove original figure labels or alter scientific data.

## Output files

Generate a minimal but complete output package by default.

### 1. `output/final_presentation_cn.pptx`
The main deliverable: a complete Chinese PPTX deck with figures, captions, takeaways, source labels, and speaker notes.

### 2. `output/qa_report.md`
A short quality report: PPTX creation status; slide count; figures inserted; missing or placeholder figures; figure-crop QA results; alignment checks; de-template language scan; self-review defects found, grouped by severity; defects corrected during the revision pass; text overflow and text-fit checks performed; design-rhythm / anti-template review performed; verification method used after revision; known limitations; manual follow-up if needed.

### 3. `output/assets/figures/`
Extracted or cropped figure assets used in the deck.

### 4. `output/asset_manifest.md`
Figure asset traceability file, generated only when external figure/table assets are extracted: asset filename; original figure / panel; source page or source file; extraction method; slide placement; crop rectangle or page-render method when known; quality notes, including whether titles, axes, legends, scale bars, table headers, and panel labels are preserved.

If no external figure/table assets are extracted, omit `asset_manifest.md` or write a one-line note in `qa_report.md` instead.

### Optional files
Create these only when useful for review, debugging, or user-requested traceability, and skip them by default unless they materially reduce back-and-forth:

- `output/ppt_outline_cn.md` — Chinese outline: paper information, paper type, central argument, slide structure, slide purpose.
- `output/figure_plan.md` — figure selection plan: figure / panel, what it shows, why it matters, recommended slide, Chinese caption, interpretation.
- `output/ppt_script_cn_with_figures.md` — slide-by-slide script (Purpose / Layout / On-slide bullets / Figure-Table / Chinese caption / Core takeaway / Speaker note per slide).
- `output/rendered/` — rendered slide previews only when a reliable headless renderer is available or the user requests visual QA.

## Quality rules

- Build the `.pptx` whenever tooling is available; do not stop at a markdown outline or script.
- Do not fabricate results, methods, numbers, or figure details.
- Do not add expensive processing steps unless they improve the deck or were requested.
- Do not overload slides with text.
- Do not deliver slides with text extending beyond visible boxes, clipped by boxes, or likely to overflow after font substitution.
- Do not make result slides text-only when figures are available.
- Make every slide serve the paper's argument.
- Ensure figures are readable at presentation scale, and that selected crops preserve all scientifically necessary context before placement. Cropped-off axes, legends, panel labels, scale bars, method labels, or table headers are delivery blockers.
- Ensure text, captions, and figures do not overlap.
- Ensure font hierarchy is consistent across slides and that figures, captions, source labels, and metrics feel visually related rather than independently placed.
- Ensure layout alignment is intentional: repeated title blocks, figure edges, caption/source strips, and bottom notes should share stable guides rather than drifting by a few points.
- Ensure Chinese expression is academic and source-specific; remove obvious AI-template phrases and repetitive slogan patterns.
- Ensure the visual rhythm does not feel like a repeated AI template; vary composition based on evidence role and figure geometry.
- Ensure the deck is not visually underfilled: empty regions should be intentional whitespace, not leftover template space.
- Run at least one self-review and corrective revision pass; do not deliver a first draft with known high-severity defects.
- Run `scripts/audit_pptx_quality.py` on the PPTX when possible and include the report path or summary in `qa_report.md`.
- Document uncertainty and missing source material clearly.

## Fallback rules

If only partial content is available: still create a useful PPTX structure when possible; clearly mark uncertain slides or missing details; use placeholders only when a required figure is unavailable; do not invent exact values or claims; write `output/qa_report.md` explaining what could not be verified.

If PPTX tooling is unavailable: generate a concise markdown outline and figure plan; prepare figure assets if possible; explain why the PPTX could not be built in the current environment; keep the outputs structured enough for a downstream PPTX builder to run without re-reading the paper.

# Core principles (paper2ppt)

## Purpose

Transform a scientific paper or paper-derived notes into a complete Chinese, figure-integrated PPTX presentation package with a Nature-style reporting logic.

The skill must not stop at an outline or script. The expected end product is a real `.pptx` deck. Keep supporting files minimal unless the user asks for more traceability.

Use this skill for papers across scientific fields, including life sciences and medicine; chemistry and materials science; environmental and earth sciences; physics and engineering; computational biology, AI, and methods papers; interdisciplinary Nature-family style research; and reviews, perspectives, resources, datasets, and benchmark papers.

## Core principle

Use the paper's scientific argument as the presentation spine. The default slide logic should help the audience answer, in order:

1. Why does this problem matter?
2. What gap or bottleneck does the paper address?
3. What did the authors do?
4. What is the key evidence?
5. Why should we trust the result?
6. What is new, reusable, or broadly meaningful?
7. Where are the boundaries and open questions?

This is more important than copying the paper section order.

## Lean operating mode

Default to the lowest-overhead workflow that still produces a usable PPTX.

Do:
- read only the source material needed to understand the paper's argument,
- extract only figures/tables that will actually appear in the deck,
- create the PPTX as the primary deliverable,
- design slides with varied, evidence-led composition rather than rigid AI-looking card templates,
- prevent text overflow by writing shorter on-slide copy, using larger text boxes, and splitting slides when needed,
- run at least one self-audit and correction pass on the generated PPTX,
- run lightweight structural checks on the PPTX package after revision,
- write a short QA report.

Avoid by default:
- exhaustive extraction of every figure, page, image, table, or supplement,
- full OCR unless normal text extraction fails or the PDF is scanned,
- saving full raw extracted paper text unless it is needed for debugging or reuse,
- installing new dependencies when an existing tool can complete the task,
- launching GUI apps or desktop automation just to render previews,
- generating long markdown scripts when the user only needs a deck,
- rendering every slide when no reliable headless renderer is available.

## Accepted inputs

The skill may receive: a full paper PDF; supplementary figures or tables; Word or markdown converted paper text; abstract + results + figure legends; structured reading notes; manually pasted article content; an `input/source.md` file; or a user-provided PPTX template.

Default output language is simplified Chinese unless the user requests otherwise. Preserve important technical terms, abbreviations, gene/protein names, model names, dataset names, equations, and statistical terms in English when needed, and keep them consistent via the Terminology Ledger.

# Toolchain policy and fast path

## Toolchain policy

Use a cross-platform Python-first stack unless the user explicitly asks for something else:

- PyMuPDF for metadata, text extraction, page rendering, and page-level crops,
- Pillow for figure crops, contact sheets, and lightweight preview images,
- python-pptx for slide authoring and PPTX-safe editing,
- zipfile plus a reopen pass through python-pptx for package validation.

This stack must work on macOS, Linux, and Windows. Use `pathlib` paths, project-local output directories, and Office-safe fonts or theme fonts. Do not hardcode OS font paths or platform-specific file locations. If Python packages are missing, create a local virtual environment and install the minimum packages only when policy permits; do not install broad document suites just to finish a normal deck.

Treat LibreOffice/soffice as optional, only when it is already available and a real rendered preview is worth the cost. Avoid Keynote, PowerPoint desktop automation, AppleScript, Preview, Finder, `open`, and any OS-specific font or path dependency in helper scripts. If a preview can be made from extracted slide objects or assets, prefer that over re-rendering the whole deck.

Ask or document the tradeoff before doing expensive extras such as full supplementary-material processing, high-resolution recreation of many figures, full slide-by-slide rendered QA, or very long decks.

## Default fast path

For a normal selectable-text paper PDF, run the shortest complete path:

1. Extract metadata, abstract, headings, figure legends, and table captions with PyMuPDF.
2. Identify the paper type, argument, and candidate figures before rendering high-resolution pages.
3. Render low-resolution contact sheets only when figure locations are unclear.
4. Render high-resolution images only for selected figure/table pages and crop only assets that will appear in the deck.
5. Build the PPTX directly with python-pptx, using native tables/charts when values are explicit and figure crops when the original visual carries the evidence.
6. Run the self-review and revision loop: inspect crop quality, slide density, layout bounds, source labels, notes, and figure readability; fix high- and medium-severity issues before final validation.
7. Verify by reopening the PPTX and inspecting package structure; render slide previews only if a reliable cross-platform headless renderer is already available.

OCR, full supplementary extraction, all-page high-resolution rendering, all-slide rendered QA, and long script files are opt-in or justified exceptions, not defaults.

# Workflow

Run these nine steps for any paper-to-deck job. The paper-type fragment loaded for this job sets the narrative arc; this workflow is the shared spine. Deep design, figure, and self-review material lives in the on-demand references named below.

## Step 1. Read and extract source material

Extract, when available: title, authors, journal/preprint server, year, DOI; field and subfield; paper type; central problem and knowledge gap; main claim or thesis; study design, workflow, model, dataset, or experimental system; key methods and controls; main results and quantitative findings; key figures, tables, and figure legends; validation, robustness, ablation, or sensitivity analyses; limitations and unresolved questions; broader scientific, clinical, technical, environmental, or translational meaning.

Do not invent missing numbers, mechanisms, datasets, or figure details. Use a two-pass reading strategy: first capture metadata, abstract, headings, figure legends, and table captions; then read only the result and methods pages needed to support the slides. Start the Terminology Ledger here.

## Step 2. Classify the paper and choose the presentation logic

The router already detected the `paper_type` axis and loaded the matching arc fragment. Confirm the classification against the source, then follow that fragment's arc (`claim-first`, `question-to-evidence`, `problem-to-solution`, `workflow-to-validation`, or `evidence-map`) when ordering slides.

## Step 3. Build the Chinese presentation plan

Default length: 12-16 slides for a 15-20 minute report; prefer 10-14 for a quick or unspecified request; expand beyond 16 only for a detailed seminar deck or when the paper genuinely needs the space. Use the default slide structure from the loaded paper-type fragment and adapt it to the paper. Do not force every paper into the same template.

Before authoring, plan the visual rhythm: assign each slide a visual role and a composition type, and avoid repeating the same role/composition too often. For the composition-type catalogue and the rule against single-layout-family decks, open `references/design-and-layout.md`.

## Step 4. Select figures as evidence, not decoration

Prioritize figures that carry the argument: design/workflow, main evidence, validation/robustness, mechanism/model/synthesis, then practical/conceptual implication. Prefer a few readable key panels over many unreadable full figures. For the full selection checklist, open `references/figure-assets.md`.

## Step 5. Extract and prepare figure assets

Extract or render only selected figures, crop dense panels, keep original data visuals unchanged, save under `output/assets/figures/`, and record traceability in `output/asset_manifest.md`. For a standard 10-14 slide deck, usually select 4-8 assets. Prefer editable PPT-native tables/charts when values are explicit. Run the figure-crop self-check before insertion. A crop that removes panel letters, axes, legends, scale bars, method labels, table headers, or scientifically necessary annotations is a high-severity defect and must be re-extracted, expanded, or split into multiple slides before insertion. Full extraction, crop, and self-check rules are in `references/figure-assets.md`.

## Step 6. Write slide-by-slide content

For each slide write: Chinese title (conclusion-style where possible), slide purpose, suggested layout, 2-4 concise Chinese bullets, the selected figure/table asset if any, Chinese caption and interpretation, one core takeaway sentence, and a concise Chinese speaker note when oral explanation helps. Each slide makes one point. Avoid template-like phrases such as “一句话总结”, “最有价值的后续方向”, “不是……而是……”, generic “提供新视角”, or repeated slogan structures; use paper-specific, evidence-grounded Chinese instead.

Respect the on-slide text budget: write for the slide, not the manuscript; most explanation belongs in speaker notes. Order each result slide as hero evidence first, then a narrow interpretation rail, then only the minimum labels. The detailed text budget, evidence hierarchy, layout-adaptation, anti-template, archetype, title, and density rules are in `references/design-and-layout.md`.

## Step 7. Build the actual PPTX deck

Create a real `.pptx` as the primary deliverable with `python-pptx` (or a user-provided template) using 16:9 by default, Chinese titles/bullets/captions/notes, source labels on figure slides, content-sized text boxes with conservative margins and no expected clipping, and consistent typography. Let slide geometry follow the figure rather than forcing the figure into a fixed 1:1 template. Align titles, figure edges, source labels, caption bands, and bottom notes to a small set of slide guides; avoid near-miss alignment where objects are off by only a few points. Treat automatic text shrinking as a last resort: prefer shorter text, larger boxes, or splitting the slide; never deliver a slide whose text is expected to overflow or be clipped. Full composition and text-fitting implementation rules are in `references/design-and-layout.md`.

## Step 8. Self-review and corrective revision loop

After the first draft, run at least one explicit self-review pass as a defect-finding step: inspect the PPTX and assets, write a severity-graded defect list (`high`/`medium`/`low`) with slide numbers, fix every high-severity issue and every reasonable medium one, regenerate, and update `output/qa_report.md`. When a `.pptx` exists, run `scripts/audit_pptx_quality.py output/final_presentation_cn.pptx --report output/pptx_audit.md` before and after revision, then copy the high/medium findings into the QA report. The full checklist, severity rules, programmatic PPTX checks, and rendered-preview policy are in `references/self-review.md`.

## Step 9. Final verification

Reopen the PPTX, check slide count, embedded media count, and speaker-notes presence when planned, check shape bounds if tooling supports it, create or inspect a contact sheet from cropped assets, and confirm `scripts/audit_pptx_quality.py` has no unresolved high-severity findings. Do not stop at "PPTX opens" if self-review found high-severity issues — fix them first, then verify again, and document any remaining limitation in `output/qa_report.md`. See `references/self-review.md`.

# Paper type: clinical / population / intervention

Covers clinical trials, population studies, intervention studies, and meta-analyses or systematic reviews of clinical evidence.

## Presentation arc — design-to-inference

Best when study design and statistical inference carry the credibility. Order the story as:

1. the clinical or public-health problem,
2. the study question,
3. the cohort / trial / design,
4. endpoints and variables,
5. the primary result,
6. subgroup / sensitivity / secondary analyses,
7. bias, limitations, and practical implication.

## Default slide structure (adapt, do not force)

1. 标题页
2. 研究背景：临床/公共卫生问题
3. 研究问题与目标
4. 研究设计：队列/试验/抽样（含 CONSORT/流程图）
5. 终点指标与变量
6. 主要结果（生存曲线、森林图、校准曲线等）
7. 亚组 / 敏感性 / 次要分析
8. 偏倚与局限性
9. 临床意义与应用
10. 总结

Report effect sizes, confidence intervals, and p-values exactly as in the paper; do not round or restate them loosely. Use survival curves, forest plots, and calibration curves as hero evidence. Be careful not to overstate causal claims beyond the study design.

# Paper type: discovery / mechanism

Covers discovery and mechanism papers: omics, single-cell, spatial, or multi-modal studies, and any work whose core is a newly observed phenomenon or an explained mechanism.

## Presentation arc — question-to-evidence

Best when the paper asks an open question and answers it through a chain of evidence. Order the story as:

1. phenomenon and why it matters,
2. the unknown mechanism or gap,
3. the hypothesis or question,
4. experimental design,
5. the evidence chain (the main result slides),
6. the mechanistic model,
7. limitations and next experiments.

If the paper has one strong central claim, you may open `claim-first` and then justify it with the same evidence chain.

## Default slide structure (adapt, do not force)

1. 标题页
2. 研究背景：为什么这个现象/问题重要
3. 知识缺口：未知的机制或矛盾
4. 核心问题与假设
5. 研究设计 / 实验体系
6-8. 关键证据 1-3（构成证据链）
9. 验证、对照或稳健性证据
10. 机制模型 / 综合框架
11. 创新点与生物学意义
12. 局限性与未解决问题
13. 总结与讨论

Emphasise the evidence chain: each result slide should advance the mechanistic argument, not just display a figure. Let the mechanism/model slide synthesise the chain.

# Paper type: materials / chemistry / physics / engineering

Covers materials, chemistry, physics, and engineering performance studies whose core is a designed material, device, or system and its measured performance.

## Presentation arc — property-to-mechanism or design-to-performance

Best when a target property or technical challenge drives a design that is then characterised and explained. Order the story as:

1. the target property or technical challenge,
2. the design principle,
3. synthesis / fabrication / setup,
4. characterisation,
5. performance evidence,
6. mechanism or structure-property relationship,
7. scalability, stability, or application boundary.

## Default slide structure (adapt, do not force)

1. 标题页
2. 研究背景：目标性能 / 技术挑战
3. 设计思路 / 原理
4. 合成 / 制备 / 实验装置
5. 表征结果
6-7. 性能证据（关键对比）
8. 机制 / 构效关系
9. 稳定性 / 可扩展性 / 应用边界
10. 局限性
11. 总结

Keep characterisation panels (XRD, SEM/TEM, spectra, performance curves) readable — crop to the key panel rather than shrinking a dense multi-panel figure. Keep units, chemical formulae, and material names exact and consistent.

# Paper type: methods / AI / tool / algorithm

Covers methods, algorithm, tool, model, and system papers across fields, including AI and computational methods.

## Presentation arc — problem-to-solution

Best when the paper proposes a procedure and must show it works and is better. Order the story as:

1. the current bottleneck or limitation,
2. the proposed method,
3. the workflow or architecture,
4. the evaluation design,
5. performance compared with baselines,
6. ablation, robustness, or failure cases,
7. reuse scenarios and limitations.

## Default slide structure (adapt, do not force)

1. 标题页
2. 研究背景：当前方法的瓶颈
3. 核心问题：要解决什么
4. 方法总览 / 架构图（通常 full-width 流程图）
5. 关键设计 / 模块
6. 评测设置：数据集、基线、指标
7-8. 主要性能结果（与基线对比）
9. 消融 / 稳健性 / 失败案例
10. 方法优势与适用边界
11. 复用场景与开源情况
12. 局限性
13. 总结

Use editable PPT-native tables/charts for benchmark numbers when values are explicit. Keep model names, dataset names, and metric names identical to the paper via the Terminology Ledger. The architecture/workflow slide is usually a full-width process diagram, not a two-column split.

# Paper type: resource / dataset / atlas / omics / benchmark

Covers resource, dataset, atlas, and benchmark papers, and large-scale omics or mapping efforts whose value is the resource itself.

## Presentation arc — workflow-to-validation

Best when the contribution is a resource that must be shown to be well-built and reusable. Order the story as:

1. why the resource is needed,
2. dataset / cohort / sample design,
3. generation and quality-control workflow,
4. the main landscape or map,
5. validation and reproducibility,
6. example biological or technical insights,
7. access, reuse, and boundaries.

## Default slide structure (adapt, do not force)

1. 标题页
2. 研究背景：为什么需要这个资源
3. 资源概览：规模、覆盖、特点
4. 样本 / 队列 / 数据设计
5. 生成与质量控制流程（full-width 流程图）
6. 主要图谱 / landscape
7-8. 关键发现 / 示例洞见
9. 验证与可复现性
10. 访问、复用与许可
11. 局限性与边界
12. 总结

The landscape/map slide is usually the hero figure — let it own the page. Keep access details (accession numbers, URLs, licences) accurate and consistent.

# Paper type: review / perspective / commentary

Covers reviews, perspectives, and commentaries that synthesise a field rather than report new primary data.

## Presentation arc — evidence-map

Best when the contribution is organisation and synthesis of existing knowledge. Order the story as:

1. why the topic matters now,
2. the conceptual framework,
3. theme 1,
4. theme 2,
5. theme 3,
6. controversy or unresolved problem,
7. the author's synthesis,
8. future directions.

## Default slide structure (adapt, do not force)

1. 标题页
2. 为什么这个主题现在重要
3. 概念框架 / 全局地图
4-6. 主题 1-3（每个主题一张证据/示意）
7. 争议 / 未解决的问题
8. 作者的综合观点
9. 未来方向
10. 总结

A review deck leans more text- and schematic-led than a primary-research deck, but still avoid dense bullet pages: use a conceptual framework diagram as the spine, and give each theme one clear visual or schematic. Attribute key ideas to their original sources, not to the review alone.