research-slide-deck-builder

Research Slide Deck Builder

目的

研究コンテンツを、ストーリー、スライドの順序、ページ単位のレイアウト、図の配置、発表者ノート、実際のデッキソースを含む、わかりやすいスライドデッキに仕上げます。

進捗報告、アドバイザーとの面談、研究室、研究の最新情報を共有するためのデッキを作成する際は、外部の progress-slides テンプレートリポジトリを優先的な実装の土台として使用します。

https://github.com/a-green-hand-jack/progress-slides.git

このテンプレートをこのスキル内に複製しないでください。ユーザーのプロジェクト内でクローン、確認、インストール、編集する外部のスライドコンポーネントまたはプロジェクトテンプレートとして扱ってください。

ユーザーがすでにスライドを持っており、時間配分、口頭でのつなぎ、リハーサル、質疑応答の練習を希望する場合は、後で presentation-dry-run を使用してください。

使用する場面

• アドバイザーとの面談、研究室の会議、グループ向けの進捗報告、論文紹介、学会発表、研究計画、または論文審査の一部に向けたスライドが必要な場合。
• デッキの見た目、スライドの枚数、タイトルページ、各ページの構成について質問された場合。
• progress-slides または再利用可能なスライドテンプレートの使用を求められた場合。
• project-init プロジェクトに、内容の作成、セットアップ、保守が必要な slides/ コンポーネントがある場合。
• 研究ノート、図、実験レポート、またはプロジェクトの記憶をプレゼンテーションにまとめる場合。

テンプレートの方針

• ユーザーが別の形式を明示的に希望しない限り、研究の進捗、アドバイザーとの面談、研究室、プロジェクトの最新情報を共有するデッキには progress-slides を優先してください。
• テンプレートのコードは上流のリポジトリに保持してください。このスキル内で CSS、コンポーネント、テーマ、パッケージ設定、ビルドパイプラインを再実装しないでください。
• 編集前に、クローンしたテンプレートの README.md、package.json、既存のスライドソースファイルを確認してください。外部リポジトリが信頼できる唯一の情報源です。
• リポジトリが非公開、または一時的に利用できない場合は、その障害を記録したうえで、後からテンプレートに移せるデッキのアウトラインまたは Markdown ソースを作成してください。
• ユーザーがプロジェクト制御ルート構成の中にいる場合は、テンプレートを独立したコンポーネントリポジトリとして <ProjectName>/slides/ に配置するか、そこに接続してください。

progress-slides のインストールまたは接続

新しいスライドコンポーネントの場合：

git clone https://github.com/a-green-hand-jack/progress-slides.git slides
cd slides

次に、テンプレートを確認します。

ls
cat README.md
cat package.json

テンプレートのロックファイルまたは README に示されているパッケージマネージャーを使用して、依存関係をインストールしてください。より優先度の高いローカルの指示がない場合は、次を使用してください。

npm install

package.json に記載されたローカルのプレビューコマンドを実行してください。Slidev 形式でよく使われるコマンドは次のとおりです。

npm run dev
npx slidev

既存のプロジェクトの場合：

• slides/ がすでにテンプレートリポジトリである場合は、その中を直接編集してください。
• slides/ が存在するもののテンプレートではない場合は、移行するか、progress-slides を新しい独立リポジトリとして追加するか、互換性のあるアウトラインのみを作成するかをユーザーに確認してください。
• テンプレートが Git を使用している場合は、その履歴を保持し、slides/ 内から通常の Git 操作を行ってください。

マルチデッキコンポーネントモデル

研究プロジェクトでは通常、期間を通じて多くのデッキが必要になります。slides/ は、永続的な slides.md を1つだけ置く場所ではなく、デッキ用のワークスペースとして扱ってください。

推奨する構成：

slides/
├── slides.md                 # optional active/scratch deck or template index
├── decks/
│   ├── 2026-05-02-advisor-plan.md
│   ├── 2026-05-09-lab-update.md
│   ├── 2026-05-15-result-review.md
│   ├── neurips-rebuttal-risk-review.md
│   ├── assets/               # deck-local assets when Slidev root is decks/
│   ├── setup/
│   └── styles/
├── assets/
│   └── <shared-or-root-deck-assets>
├── templates/
├── snippets/
└── .agent/
    ├── slides-status.md      # component-level status
    ├── deck-index.md         # registry of decks
    └── decks/
        └── 2026-05-02-advisor-plan.md

次の方針を使用してください。

• 実際の会議用には、decks/<date>-<audience-or-purpose>-<slug>.md に固定のデッキを作成します。
• ルートの slides.md は、現在のデフォルトデッキ、一時的な作業用コピー、またはテンプレートのサンプル／インデックスデッキに限って使用します。
• 新しいアドバイザー向け／研究室向けの進捗報告を始める際に、過去の会議用デッキを上書きしないでください。
• 再利用可能な単一スライドの断片は snippets/ に、過去のデッキ全体は decks/ に保存します。
• 生成された出力は dist/ または無視対象のエクスポート用パスに保存し、正本として扱わないでください。
• デッキ固有のアセットには、アクティブな Slidev ルート配下のアセットを優先してください。エントリが decks/<deck-id>.md の場合は、decks/assets/<deck-id>/... を使用し、デッキから ./assets/<deck-id>/... として参照します。アクティブなエントリから解決できることが確認済みのアセットに限り、assets/shared/... を使用してください。
• テンプレート CLI が slides.md にしか書き込めない場合は、まずそこで初期化し、完成したソースを decks/<deck-id>.md に移動またはコピーします。または、利用できる場合は --out decks/<deck-id>.md オプションを使用します。

デッキの記録を管理します。

• slides/.agent/slides-status.md：コンポーネントの状態、アクティブなデッキ、最近のデッキ、古くなった根拠資料、ビルド／エクスポート方針
• slides/.agent/deck-index.md：各デッキについて、id、パス、対象者、日付、目的、根拠資料、検証状況、フォローアップを1行ずつ記載
• slides/.agent/decks/<deck-id>.md：重要なデッキについて、デッキの要件、根拠資料、視覚的な検証、未解決のリスクなどを記録する任意のデッキごとのメモ

デッキ設計の原則

• 1枚のスライドには1つの役割を持たせます。すべてのスライドに、要点を一文で示す必要があります。
• 聴衆がたどる流れを明確にします：背景 -> 問い -> 根拠 -> 判断。
• アドバイザー向けの進捗報告では、洗練されたストーリーテリングよりも、判断事項、障害、根拠を優先します。
• 研究発表では、動機、問題の枠組み、手法の直感的な説明、結果の解釈を優先します。
• 図は装飾ではなく根拠です。軸、設定、要点を説明します。
• スライドのタイトルは具体的にします。「結果」「手法」「実験」のような一般的なタイトルは避けてください。
• 詳細が詰まっている場合は、文字を小さくするのではなく、補足スライドに記載します。
• ビルドの成功は、見た目の成功を意味しません。Slidev デッキはコンパイルできても、ブラウザー表示では、はみ出し、壊れたフロントマター、アセットの欠落、読みにくいコードのハイライト、上部に偏ったレイアウト、または発表には情報量が多すぎるスライドが残ることがあります。

デッキの要件

スライドのソースを書く前に、簡潔なデッキ要件を定めます。

• deck_scope：このデッキで扱うことが許可される唯一のストーリーの範囲
• allowed_terms：FK-Doob-PhysGen など、記載するべきプロジェクト名や発表用語
• banned_terms：聴衆向けのテキストに含めてはならない実装名、古いプロジェクト名、または経路を示す語
• one_sentence_claim：聴衆に覚えてもらうべき一文
• project_title：タイトルスライドとデッキのメタデータに記載する必要がある正確なプロジェクト名

作成後、スライドのソースから禁止用語や古い用語を検索します。実装時には内部コード名が役立っても、聴衆にとって紛らわしい場合は、技術的に必要な箇所に限って実装名を残し、見出しや要点では発表用語に置き換えます。

デフォルトの命名規則：タイトルスライド、ブラウザー／PDF のメタデータ、最初の H1 には、プロジェクト名を含める必要があります。ユーザーが明示的に求めない限り、手法だけを示すタイトルは使用しないでください。

ワークフロー

1. 発表の種類を特定する

以下を決定します。

• decks/ 配下のデッキ id と保存先パス
• 対象者：アドバイザー、研究室、委員会、学会、面接、または授業
• 持ち時間
• 目的：フィードバック、進捗報告、教育、説得、または審査
• 最も重要な要点1つ
• 利用可能な資料：メモリ、ノート、図、レポート、論文の草稿、コードの結果、または既存のスライド
• デッキの要件：範囲、使用許可された用語、使用禁止の用語、一文の主張、正確なプロジェクト名

2. スライドデッキのアーキタイプを選ぶ

最も近いアーキタイプを選びます。

アドバイザー向け進捗報告デッキ：

1. タイトル／ミーティングの目標
2. 前回のコミットメント
3. 進捗の概要
4. 主要な成果または根拠
5. 解決したこと
6. 行き詰まっていること
7. 選択肢／必要な判断
8. 来週の計画

ラボミーティングでの研究進捗報告：

1. タイトル
2. 課題と動機
3. 現在の研究課題
4. 手法またはセットアップ
5. 実験のセットアップ
6. 主な結果
7. アブレーション／分析
8. 限界または失敗例
9. 次のステップと質問

論文読解レポート：

1. タイトル：論文とその重要性
2. 1文で述べる貢献
3. 問題設定
4. 手法の概要
5. 重要な技術的アイデア
6. 主な実験
7. 強み
8. 弱み／前提
9. ユーザーのプロジェクトとの関連性
10. 議論のための質問

カンファレンス形式の講演：

1. タイトル
2. 動機
3. 課題
4. 先行研究のギャップ
5. 手法の直感的な説明
6. 手法の詳細
7. 実験のセットアップ
8. 主な結果
9. 分析／アブレーション
10. 限界
11. 要点

3. 大幅な編集の前にスライド計画を作成する

スライドごとに、次の内容を書き出します。

• スライド番号
• スライドの種類
• 要点を示すタイトル
• 必要なビジュアル／根拠
• 箇条書きまたは図の内容
• 発表者ノート
• リスク：聴衆が混乱する可能性のある点

要点がないスライドは、統合するか、削除するか、補足資料に移します。

ソースを編集する前に、容量の予算を設定します。

• 通常のスライドは、H1を1つ、主要なビジュアル領域を1つ、要点を1つまでにします。
• 通常のスライドに、質問ボックス、長い箇条書き、コードブロック、要点を一緒に配置しないでください。
• 通常のスライドのコードブロックは、通常3行までにします。それより長いコードは補足資料に入れます。
• 表は、文字を読めるサイズより小さくせずに16:9の画面内に収めます。
• 3列レイアウトでは、ビジュアルデザインが明確に対応できる場合を除き、各列の箇条書きは3項目程度にします。
• 補足スライドは情報量が多くてもかまいませんが、それぞれに目的が必要です。参照リンク、アセットのパス、実装の詳細、追加の根拠などを示します。

4. テンプレートに対応したソースを書く

progress-slides を確認した後、テンプレートで既に使われている形式で記述します。Slidev 形式の Markdown では、次のパターンを優先してください。

---
theme: default
title: Project Progress Update
---

# Specific Takeaway Title

- Evidence or status point
- Decision or implication



---

# Main Result Supports the Current Claim

<figure-or-table-placeholder>

- Setup:
- Metric:
- Interpretation:

テンプレートがノートに対応している場合は、スピーカーノートをスライドのソースの近くに配置します。デッキを移動または共有できるよう、画像パスはスライドデッキからの相対パスにします。

Slidev ソースのガードレール：

• デッキ全体の frontmatter は、デッキの先頭にのみ配置します。
• スライドごとの frontmatter は、それだけで有効な frontmatter ブロックにします。

---
layout: center
class: text-center
---

• スライドごとの frontmatter が不要なページでは、省略します。通常の Markdown 本文に layout: や class: の行を残さないでください。
• 編集後、ソースを大幅に変更した場合は、frontmatter ブロックの外にある ^layout: と ^class: を検索します。
• エクスポートした PDF やブラウザーのタイトルで識別できるよう、タイトルのメタデータにはプロジェクト名を含めます。
• デッキのソースが decks/ の下にある場合は、既定の slides.md が対象だと決めつけず、npx slidev decks/2026-05-02-advisor-plan.md のように、そのファイルを指定して Slidev を実行します。

Slidev のルート、アセット、スタイルに関するガードレール：

• パスを記述する前に、エントリーファイルから有効な Slidev ルートを特定します。slides/decks/<deck-id>.md の場合、ルートは slides/ ではなく slides/decks/ の可能性があります。
• 単独で使用する会議用アセットは、slides/decks/assets/<deck-id>/figure.png のように、有効なルート内のデッキ専用ディレクトリに配置し、slides/decks/<deck-id>.md からは ./assets/<deck-id>/figure.png として参照します。
• 会議用デッキでは、実行中のコードワークツリー内のパスに依存しないでください。安定したプレゼンテーション用の図を、デッキ専用のアセットディレクトリにコピーします。
• デッキ全体に適用する CSS は、slides/decks/styles/index.css のように有効な Slidev ルートの下に配置し、import '../styles/index.css' を使って slides/decks/setup/main.ts から読み込みます。
• デッキ全体のスタイル設定を、大きな Markdown の <style> ブロック 1 つに依存させないでください。スライド間で一貫して適用されない場合があります。
• コードまたはパイプラインのスライドでは、Shiki がハイライト表示した入れ子の span を確認します。ローカルスタイルの可読性が低下した場合は、該当するスライドブロックの pre、code、code span の色を上書きします。
• 結果を示す図では、レイアウトを選ぶ前に実際の画像サイズを確認します。

sips -g pixelWidth -g pixelHeight <figure>.png

• 図を 2 つ並べるスライドは、通常の画像グリッドとは別にサイズを調整します。科学的なプロットを 2 つ並べる場合、一般的なカード画像よりも大きな縦方向のスペースが必要になることがよくあります。

5. プロジェクトの根拠を適切に使う

• 安定した図は、code/docs/results/、code/docs/reports/、論文の図、またはユーザー提供のアセットから取得します。
• 生ログ、大きな出力、チェックポイント、wandb／tensorboard のキャッシュをスライドリポジトリにコピーしないでください。
• 図が古い、不明瞭、または情報過多の場合は、デッキを仕上げる前に figure-results-review を使います。
• スライドの主張が論文やプロジェクトの状況と食い違う場合は、そのリスクを memory/ または slides/.agent/ に記録します。

6. ストーリーと用語を検証する

ビルドまたはエクスポートの前に、次の点を確認します。

• 最初のスライドのタイトル、ブラウザー／PDF のタイトルメタデータ、メインの H1 にプロジェクト名が含まれている
• 通常のスライドごとに、伝えるべき要点が 1 つある
• 聴衆向けの見出しと要点に、banned_terms、古いプロジェクト名、内部実装名が含まれていないか検索する
• デッキの範囲で明示的に認められていない限り、最後のスライドで動機付けのない新しい方向性を持ち出していない
• 要点には「isometric conditional model」などのプレゼンテーション向けの用語を優先し、model_D などの実装用語は実装の詳細を説明するスライドにとどめる

7. デッキを検証する

完了する前に、次の点を確認してください。

• 依存関係が利用可能な場合は、テンプレートのプレビュー／ビルドコマンドを実行します
• デッキがローカルで開くことを確認します。スライドが見た目にも使用可能である証明として、npm run build だけを扱わないでください
• Markdown ソースだけでなく、ブラウザーのプレビューで、すべての画像パスが解決されることを確認します
• グローバル CSS がアクティブな Slidev ルートから読み込まれていることを確認します
• 16:9 のプレゼンテーション表示で、テキストが読みやすいことを確認します
• 各結果スライドで、セットアップ、指標、解釈が説明されていることを確認します
• 1 枚目、2 枚目、最後の 3 枚を目視で確認します。タイトル、構成、締めくくりの間違いは大きな影響を与えるためです
• 代表的なスライドを 16:9 でスクリーンショットに撮ります。テキストの多い／背景説明のスライド、表または指標のスライド、図を 2 つ並べたスライド、コードまたはパイプラインのスライド、バックアップスライドのレイアウトが異なる場合はそのスライドを含めます
• 可能な場合は、テンプレートのエクスポートコマンド、Slidev のブラウザーエクスポート UI、または slidev export --format png を使って PNG／PDF をエクスポートします。Slidev CLI によるエクスポートには Playwright／playwright-chromium が必要です
• Playwright または Chromium がないために PNG／PDF をエクスポートできない場合は、不足している依存関係を記録し、代わりにブラウザーのプレビューでスクリーンショットを撮るか、ブラウザーで手動確認します
• 表、コードブロック、3 列レイアウト、質問ボックス、要点ボックスで、内容がはみ出していないことを確認します
• はみ出しがなくても、上部に過剰な余白が集中している場合はレイアウトの問題として扱います。すべての要素を上部に積み重ねるのではなく、スライドごとのクラスで内容を再配置してください
• 特に並列配置されたプロットでは、科学的な図を目視で確認できる十分な大きさにします
• プロジェクト管理ルート構成を使用する場合は、デッキのパス、目的、対象者、根拠となるソース、ビルド状況、視覚的な検証状況、古くなった根拠に関するリスク、未確認の既知のリスク、フォローアップの対応を記載して、slides/.agent/slides-status.md と slides/.agent/deck-index.md を更新します
• 重要なデッキや再利用するデッキの場合は、slides/.agent/decks/<deck-id>.md も作成します

最終チェックリスト：

- [ ] Deck source lives in `decks/<deck-id>.md` unless this is a temporary/default `slides.md` deck.
- [ ] `slides.md` was not used to overwrite a previous real meeting deck.
- [ ] Title includes project name.
- [ ] Deck has one explicit narrative scope.
- [ ] Banned or stale terms checked with search.
- [ ] No normal slide has H1 + question box + code block + takeaway together.
- [ ] Code blocks are <= 3 lines unless in backup.
- [ ] Tables fit within 16:9 width.
- [ ] No literal `layout:` or `class:` frontmatter is rendered as body text.
- [ ] Deck-local assets resolve from the active Slidev root.
- [ ] Global CSS is imported from the active Slidev root, not only embedded in Markdown.
- [ ] Result figure dimensions were inspected before final sizing.
- [ ] Internal code names are replaced in audience-facing text where appropriate.
- [ ] Preview/build passes, or missing dependency is recorded.
- [ ] Representative 16:9 screenshots, PNG/PDF export, or browser visual inspection completed.
- [ ] Code blocks remain readable after syntax highlighting.
- [ ] Figure slides are readable and not undersized.
- [ ] `slides/.agent/slides-status.md` and `slides/.agent/deck-index.md` updated when project memory is present.

出力形式

計画のみを求められた場合は、次の形式で出力します。

# Research Slide Deck Plan - [Deck Name]

## Context
- Audience:
- Time limit:
- Goal:
- One takeaway:
- Template: progress-slides
- Deck id:
- Deck path:
- Deck scope:
- Allowed terms:
- Banned terms:

## Slide Plan
| # | Type | Takeaway title | Visual/evidence | Speaker note | Risk |
|---:|---|---|---|---|---|

## Required Assets
- [ ] [figure/table/diagram]

## Decision Points
1. [Decision/question]

## Backup Slides
- [Backup topic]

実装を求められた場合は、クローンした progress-slides リポジトリの実際の slides/ ソースファイルを編集し、変更したパスと使用したプレビュー／ビルドコマンドを報告します。

既存の slides コンポーネントに新しいデッキを作成する場合は、次をデフォルトとします。

slides/decks/<YYYY-MM-DD>-<audience-or-purpose>-<slug>.md
slides/decks/assets/<deck-id>/...
slides/.agent/deck-index.md
slides/.agent/decks/<deck-id>.md

ユーザーが現在のデフォルトデッキを明示的に希望している場合、またはテンプレートのツールが一時的なステージングファイルを必要とする場合に限り、slides/slides.md を使用します。

禁止事項

• スキル内に独立したスライドテンプレートを作成しないでください。
• ユーザーがテンプレート自体の変更を求めていない限り、外部テンプレートを再設計しないでください。
• 根拠や意思決定を伴わないステータス箇条書きだけのデッキを作成しないでください。
• アドバイザー向けの進捗報告に、学会発表のようなストーリー構成を無理に当てはめないでください。
• 内容を省くことへの不安から、スライドに情報を詰め込みすぎないでください。
• ユーザーが開いて発表できるデッキを期待している場合、Markdown の正しさやビルドの成功だけで作業を終えないでください。
• バックアップスライドを、説明のないアセットの羅列にしないでください。
• プロジェクトのライフサイクル全体を通して、slides/slides.md だけをデッキファイルとして扱わないでください。
• すべての会議で同じファイルを使い回して、過去のデッキを失わないでください。