Skip to content

AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He

docs(topic-research): make factual preparation gap-driven

hugohe3d9fcd1960918
diff --git a/AGENTS.md b/AGENTS.md
index c4ab3476..8c99bf52 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -10,7 +10,7 @@ PPT Master is an AI-driven presentation generation system. Multi-role collaborat
**Route selection authority**: [`skills/ppt-master/workflows/routing.md`](skills/ppt-master/workflows/routing.md) owns the four top-level artifact routes: Generate PPTX, Create Template, Fill Native PPTX, and Enhance Native PPTX. Child workflows, profiles, stages, and governance documents refine one selected route; they are not competing top-level routes.
-- Topic-only requests run the [`topic-research`](skills/ppt-master/workflows/stages/topic-research.md) intake stage before [`generate-pptx`](skills/ppt-master/workflows/generate-pptx.md) Step 1.
+- Topic-only or fact-insufficient inputs run [`topic-research`](skills/ppt-master/workflows/stages/topic-research.md) in Generate Step 1; facts only, no images.
- Raw PPTX template plus new material/topic routes to [`template-fill-pptx`](skills/ppt-master/workflows/template-fill-pptx.md), not the SVG pipeline.
- Raw PPTX cannot be consumed as a Generate Step 3 SVG template; run [`create-template`](skills/ppt-master/workflows/create-template.md) first and return with the generated template workspace root. Never add Master/Layout structure directly to an existing PPTX/SVG; generate new structured SVG pages from the workspace.
- PPTX beautify is a strict 1:1 main-generation [`profile`](skills/ppt-master/workflows/profiles/beautify-pptx.md), not a separate route; any split/merge/drop/reorder uses the default main-pipeline policy.
diff --git a/docs/faq.md b/docs/faq.md
index 512eece3..3b05a66d 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -10,7 +10,7 @@ Almost anything: **PDF**, **DOCX**, **PPTX**, **EPUB**, **HTML**, **LaTeX**, **R
## Q: Can I generate a deck with just a topic, no source materials?
-Yes. Tell the AI your topic or scenario (e.g. "make a PPT about Hayao Miyazaki", "introduce our new product"). The Generate PPTX route will run its **topic-research stage** — gathering authoritative sources via web search (Wikipedia / official sites / institutional releases), assembling them into a Markdown research document + image folder, then feeding both into the main pipeline.
+Yes. Tell the AI your topic or scenario (e.g. "make a PPT about Hayao Miyazaki", "introduce our new product"). The Generate PPTX route will run its **topic-research stage** to gather the factual baseline and provenance needed for planning. If you provide partial material, the same stage may fill only the factual gaps required by your requested outcome unless you ask for a source-only result. Images are selected during Strategist planning and acquired only after final confirmation.
Quality depends on what's on the open web. If you already have specialized material (papers, internal docs), giving those files to the AI directly produces better results than web research alone.
diff --git a/docs/technical-design.md b/docs/technical-design.md
index 4d4b63d4..41fd47a1 100644
--- a/docs/technical-design.md
+++ b/docs/technical-design.md
@@ -120,7 +120,7 @@ Use this table before reasoning about implementation details. Most failed runs s
| Request shape | Route | Boundary |
|---|---|---|
-| Topic only, no source file or substantive source text | Generate PPTX + `topic-research` stage | web/source collection is a pre-pipeline stage |
+| Topic only, or supplied material lacks facts required by the requested outcome | Generate PPTX + `topic-research` inside Step 1 | topic-only research starts immediately; source-backed research follows conversion/read and fills only identified factual gaps |
| Source files or conversation text, deck structure may be rethought | Generate PPTX | Strategist may split, merge, drop, reorder, and redesign |
| PPTX as source material, user allows a new story/page structure | Generate PPTX via `ppt_to_md` + `pptx_intake` | PPTX identity/geometry are facts and candidates, not replica constraints |
| Raw PPTX template plus new material/topic | Fill Native PPTX (`template-fill-pptx`) | clone/fill native slides; no SVG generation |
@@ -403,7 +403,7 @@ The cooking analogy is the canonical ownership model for generation, not just ex
| Menu planner and preparation lead | Strategist, `design_spec.md`, `spec_lock.md`, and Strategist-owned acquisition stages | Assesses sufficiency; fills permitted factual gaps; selects the content, resources, page roster, chart/layout keys, fonts, palette anchors, icons, and crop boundaries; readies the complete project-local inventory before execution |
| Cook | Executor | Uses only the prepared inventory and realizes the plan through geometry, composition, hierarchy, spacing, and treatment without changing the selected “dish” or acquiring/substituting ingredients |
-**Preparation has two clocks.** Topic Research, when triggered, may precede final confirmation because its facts are planning input. AI / web / slice image acquisition runs only after final confirmation and the completed `design_spec.md §VIII` / `spec_lock.md`, then reaches a terminal status before Executor starts. Strategist also resolves, syncs, and validates the icon inventory while authoring the final plan. Image_Generator, Image_Searcher, and icon-sync tooling are preparation mechanisms under Strategist ownership, not independent decision owners.
+**Preparation has two clocks.** Topic Research supplies facts before final confirmation: it starts immediately for topic-only input, or after supplied material is converted/read when planning-critical factual gaps remain. It supplements only those gaps and acquires no images. AI / web / slice image acquisition runs only after final confirmation and the completed `design_spec.md §VIII` / `spec_lock.md`, then reaches a terminal status before Executor starts. Strategist also resolves, syncs, and validates the icon inventory while authoring the final plan. Image_Generator, Image_Searcher, and icon-sync tooling are preparation mechanisms under Strategist ownership, not independent decision owners.
**Prepared inventory is the boundary.** A resource is available to Executor only when Strategist has selected it, recorded it in the planning artifacts, and made its project path resolvable or explicitly `Needs-Manual`. Merely existing elsewhere on disk does not authorize its use. Missing material returns upstream; Executor never searches, generates, downloads, syncs, or substitutes it.
diff --git a/docs/zh/faq.md b/docs/zh/faq.md
index 441e99a8..7019211c 100644
--- a/docs/zh/faq.md
+++ b/docs/zh/faq.md
@@ -10,7 +10,7 @@
## Q: 只有一个主题或想法、没有任何资料,也能生成吗?
-可以。直接告诉 AI 你想做的主题或场景(如"做一个关于宫崎骏的 PPT"、"介绍我们公司新产品"),Generate PPTX 路线会自动运行 **topic-research 阶段**——通过网页搜索抓取权威来源(Wikipedia / 官网 / 机构发布),整理成 Markdown 资料文档 + 配图集后再走主流程生成幻灯片。
+可以。直接告诉 AI 你想做的主题或场景(如"做一个关于宫崎骏的 PPT"、"介绍我们公司新产品"),Generate PPTX 路线会运行 **topic-research 阶段**,补齐规划所需的事实基础与来源记录。已有部分材料时,只补实现用户目标仍缺少的事实;如果用户要求只使用原材料,则不做外部补充。图片由 Strategist 在规划中选定,并且只在最终确认后获取。
效果取决于公开网页的覆盖度。如果你已有专业资料(论文、内部文档),直接把文件给 AI 比联网检索更准。
diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.md
index ef70b645..ef39088a 100644
--- a/docs/zh/technical-design.md
+++ b/docs/zh/technical-design.md
@@ -121,7 +121,7 @@ PPT Master 不以“任意 SVG 都能转成 PPTX”为目标。`svg_output/` 使
| 请求形态 | 路线 | 边界 |
|---|---|---|
-| 只有主题,没有源文件或足够源文本 | Generate PPTX + `topic-research` 阶段 | 网络 / 来源收集是前置阶段 |
+| 只有主题,或现有材料缺少实现用户目标所需的事实 | Generate PPTX Step 1 内运行 `topic-research` | 只有主题时立即研究;有材料时先转换 / 阅读,只补已识别的事实缺口 |
| 有源文件或对话文本,deck 结构可以重想 | Generate PPTX | Strategist 可以拆分、合并、删除、重排和重设计 |
| PPTX 作为源材料,用户允许重构故事和页结构 | Generate PPTX,经 `ppt_to_md` + `pptx_intake` | PPTX 身份和几何是事实与候选,不是复刻约束 |
| 原生 PPTX 模板 + 新材料 / 新主题 | Fill Native PPTX(`template-fill-pptx`) | 克隆并填充原生页面;不生成 SVG |
@@ -399,7 +399,7 @@ Strategist 阶段产出两份看起来冗余但服务不同对象的产物:
| 菜单策划与备料负责人 | Strategist、`design_spec.md`、`spec_lock.md` 及其负责的材料获取阶段 | 判断材料是否充分;补齐获准补充的事实;选定内容、资源、页面清单、图表/版式 key、字体、色板锚点、图标和裁剪边界;在执行前备齐项目级材料清单 |
| 厨师 | Executor | 只使用已备材料,以几何、构图、层级、间距和视觉处理实现方案;不得改变所选“菜品”,也不得自行找料、换料 |
-**备料有两个时点。** Topic Research 被触发时可以早于最终确认,因为其中的事实是策略规划的输入。AI / web / slice 图片只能在最终确认以及完整的 `design_spec.md §VIII` / `spec_lock.md` 之后获取,并在 Executor 开始前进入终态。Strategist 还会在编写最终方案时解析、同步并验证图标 inventory。Image_Generator、Image_Searcher 与图标同步工具只是 Strategist 负责的备料机制,不是独立决策者。
+**备料有两个时点。** Topic Research 在最终确认前补充规划所需的事实:只有主题时立即运行;已有材料时先转换 / 阅读,仅在仍有关键事实缺口时补齐,而且不获取任何图片。AI / web / slice 图片只能在最终确认以及完整的 `design_spec.md §VIII` / `spec_lock.md` 之后获取,并在 Executor 开始前进入终态。Strategist 还会在编写最终方案时解析、同步并验证图标 inventory。Image_Generator、Image_Searcher 与图标同步工具只是 Strategist 负责的备料机制,不是独立决策者。
**已备材料清单就是边界。** 只有被 Strategist 选定、写入规划产物,并且项目路径可解析或已明确标为 `Needs-Manual` 的资源,才对 Executor 可用。文件仅仅存在于其他目录并不构成使用许可。缺料必须返回上游;Executor 不得搜索、生成、下载、同步或替换资源。
diff --git a/skills/ppt-master/scripts/prompt_audit_manifest.json b/skills/ppt-master/scripts/prompt_audit_manifest.json
index dcb13af3..747f1491 100644
--- a/skills/ppt-master/scripts/prompt_audit_manifest.json
+++ b/skills/ppt-master/scripts/prompt_audit_manifest.json
@@ -534,7 +534,7 @@
"max_tokens": 56500
},
"stage.generate.topic-research": {
- "description": "Topic-only intake stage.",
+ "description": "Gap-targeted factual intake stage.",
"scope": "incremental",
"files": [
"skills/ppt-master/workflows/stages/topic-research.md"
diff --git a/skills/ppt-master/workflows/generate-pptx.md b/skills/ppt-master/workflows/generate-pptx.md
index 009bdbf1..729ef460 100644
--- a/skills/ppt-master/workflows/generate-pptx.md
+++ b/skills/ppt-master/workflows/generate-pptx.md
@@ -6,7 +6,7 @@ description: Generate PPTX route authority for source intake, planning, SVG auth
> Load only after [`routing.md`](./routing.md) selects Generate PPTX. This file owns the route's Step 1–7 sequence, gates, role switching, and mandatory commands.
-**Core Pipeline**: `Source Document → Create Project → [Template] → Strategist Structured Plan → [Image_Generator] → Executor Live Preview → Quality Check → Post-processing → Export`
+**Core Pipeline**: `Initial Materials → [Fact Research] → Create Project → [Template] → Strategist Structured Plan → [Image Acquisition] → Executor Live Preview → Quality Check → Post-processing → Export`
**Generate-specific execution discipline**:
@@ -42,9 +42,9 @@ description: Generate PPTX route authority for source intake, planning, SVG auth
### Step 1: Source Content Processing
-🚧 **GATE**: User has provided source material (PDF / DOCX / EPUB / URL / Markdown file / text description / conversation content — any form is acceptable).
+🚧 **GATE**: The user has provided a topic / desired outcome and any available initial material.
-> **No source content?** When the user supplies only a topic name or requirements without any file or substantive description, run the [`topic-research`](stages/topic-research.md) intake stage first, then return here with its products as input.
+> **Topic-only**: run [`topic-research`](stages/topic-research.md) immediately, then use its factual supplement as source content.
When the user provides non-Markdown content, convert immediately through the
unified dispatcher. It preserves the backend converters' existing behavior,
@@ -64,6 +64,16 @@ Use `-o` only when a specific output file/directory is required; with multiple
inputs or directory inputs, `-o` is an output directory. Backend converter details are documented in
[`scripts/docs/conversion.md`](../scripts/docs/conversion.md).
+After reading direct and converted content, assess factual sufficiency:
+
+| Material state | Action |
+|---|---|
+| Requested outcome is supported | Continue Step 2 |
+| Required externally verifiable claims remain unsupported | Run [`topic-research`](stages/topic-research.md) for those gaps only |
+| Closed corpus / source-only / no external enrichment | Stay within supplied material |
+
+**Sufficiency test**: research only to avoid inventing, omitting, or leaving unsupported a factual claim the requested outcome requires; file presence or length is irrelevant. It gathers facts only. Step 5 acquires Strategist-selected images after final confirmation.
+
> **Office vector assets (EMF/WMF) from DOCX/PPTX sources**:
> Source conversion extracts embedded Office vector images (.emf/.wmf)
> alongside bitmap images when the source format exposes them. After `import-sources`, these land in `images/`
@@ -78,7 +88,7 @@ inputs or directory inputs, `-o` is an output directory. Backend converter detai
> Browser-based live preview cannot render EMF (will show blank) — this is expected;
> the PPTX output is the source of truth.
-**✅ Checkpoint — Confirm source content is ready, proceed to Step 2.**
+**✅ Checkpoint — Confirm source content and any factual supplement are ready, proceed to Step 2.**
---
diff --git a/skills/ppt-master/workflows/index.md b/skills/ppt-master/workflows/index.md
index 00ab34b8..84f4e8e2 100644
--- a/skills/ppt-master/workflows/index.md
+++ b/skills/ppt-master/workflows/index.md
@@ -24,7 +24,7 @@ Maintainer-only inventory for adding, moving, or removing workflow documents. Ru
| `create-brand` | Template child workflow | [`create-template/create-brand.md`](./create-template/create-brand.md) | Create Template |
| `create-layout` | Template child workflow | [`create-template/create-layout.md`](./create-template/create-layout.md) | Create Template |
| `create-deck` | Template child workflow | [`create-template/create-deck.md`](./create-template/create-deck.md) | Create Template |
-| `topic-research` | Intake stage | [`stages/topic-research.md`](./stages/topic-research.md) | Before Generate Step 1 |
+| `topic-research` | Factual-preparation stage | [`stages/topic-research.md`](./stages/topic-research.md) | Inside Generate Step 1 |
| `resume-execute` | Control stage | [`stages/resume-execute.md`](./stages/resume-execute.md) | Generate Step 6 resume |
| `refine-spec` | Planning stage | [`stages/refine-spec.md`](./stages/refine-spec.md) | After Generate confirmation |
| `verify-charts` | Quality gate | [`stages/verify-charts.md`](./stages/verify-charts.md) | Before Generate Step 7 |
diff --git a/skills/ppt-master/workflows/routing.md b/skills/ppt-master/workflows/routing.md
index 116a5e18..fa360735 100644
--- a/skills/ppt-master/workflows/routing.md
+++ b/skills/ppt-master/workflows/routing.md
@@ -41,7 +41,7 @@ route selection. After selection, the route authority owns execution.
| Request condition | Generate-route behavior |
|---|---|
-| Topic only, no substantive source facts | Run [`topic-research`](./stages/topic-research.md), then return to [`generate-pptx`](./generate-pptx.md) Step 1 |
+| Topic only, or supplied sources leave planning-critical factual gaps | Run [`topic-research`](./stages/topic-research.md) inside [`generate-pptx`](./generate-pptx.md) Step 1: immediately for topic-only input, or after conversion and reading for source-backed input; research only the identified gaps, then continue Step 2 |
| Existing PPTX may be split, merged, dropped, reordered, or re-outlined | Treat the PPTX as source content through [`generate-pptx`](./generate-pptx.md) Step 1 and its PPTX intake; use the default Generate pipeline |
| Existing PPTX must preserve wording, page count, and page order 1:1 | Activate the [`beautify-pptx`](./profiles/beautify-pptx.md) profile inside the main pipeline |
| Explicit current brand/layout/deck workspace root | Enter [`generate-pptx`](./generate-pptx.md) Step 3 and conditionally load [`apply-template-workspace`](./stages/apply-template-workspace.md); consume the workspace root, never only its inner `templates/` directory |
diff --git a/skills/ppt-master/workflows/stages/topic-research.md b/skills/ppt-master/workflows/stages/topic-research.md
index eee8ae09..6859ac51 100644
--- a/skills/ppt-master/workflows/stages/topic-research.md
+++ b/skills/ppt-master/workflows/stages/topic-research.md
@@ -1,99 +1,86 @@
---
-description: Main-pipeline intake stage that gathers source material for topic-only requests.
+description: Generate Step 1 intake stage that fills externally verifiable factual gaps before Strategist confirmation.
---
# Topic Research Stage
-> Generate-PPTX intake stage. Run before [`generate-pptx`](../generate-pptx.md) Step 1 when the user supplies only a topic or requirements with no source files. Output is a research document, a stable fact-provenance file, and an image folder, all shaped to feed `project_manager.py import-sources` directly.
+> Strategist-owned factual preparation inside [`generate-pptx`](../generate-pptx.md) Step 1. Run immediately for topic-only input, or after supplied material is converted and read when it leaves planning-critical factual gaps. Output is a research supplement plus stable fact provenance for Step 2 import.
-This stage is **context-independent**: it owns source acquisition when no file exists; subsequent [`generate-pptx`](../generate-pptx.md) steps proceed normally with the produced materials as input.
+This stage supplies facts needed to plan the requested deck. It does not select, download, or generate images; image selection belongs to the final Strategist plan, and AI / web / slice acquisition runs in Generate Step 5 after final confirmation.
## When to Run
-| User-supplied input | Action |
+| Material state | Action |
|---|---|
-| Topic name only (e.g. "做一个关于宫崎骏的 PPT") | Run this stage before Generate Step 1 |
-| Requirement description without facts (e.g. "介绍我们公司新产品") | Run this stage before Generate Step 1 |
-| ≥1 page of substantive content already in chat | Skip — feed chat content into [`generate-pptx`](../generate-pptx.md) Step 1 directly |
-| Source file attached (PDF / DOCX / URL / Markdown) | Skip — go to [`generate-pptx`](../generate-pptx.md) Step 1 source conversion |
+| Topic or requirements with no supporting facts | Research the factual baseline needed for the requested outcome |
+| Supplied files or chat content cover only part of the requested outcome | After conversion and reading, research only the identified externally verifiable gaps |
+| Supplied material already supports the requested outcome | Skip this stage and continue Generate Step 1 |
+| User requires a closed corpus, source-only transformation, or no external enrichment | Skip this stage and keep planning within supplied material |
+
+**Sufficiency test**: a gap exists when the Strategist would otherwise need to invent, omit, or leave unsupported an externally verifiable claim required by the user's requested outcome. File presence, source length, and a generic topic taxonomy do not decide sufficiency.
+
+**Hard rule — preserve supplied facts**: supplement the user's material; never silently replace it. Record a material source conflict for Strategist review instead of choosing a different claim without disclosure. Do not research omissions outside the requested scope.
---
-## Step 1: Confirm topic
+## Step 1: Define the gap brief
-⛔ **BLOCKING**: confirm scope as a single bundled clarifier. Skip when the user's initial message already covers it.
+⛔ **BLOCKING**: confirm only missing scope or research-boundary decisions as one bundled clarifier. Skip when the request and supplied material already make them clear.
-| Item | Default if user did not specify |
+| Item | Default if unspecified |
|---|---|
-| Topic | (from user input) |
-| Scope / focus | Broad overview |
-| Depth | General-knowledge level |
+| Topic | From the user request |
+| Requested scope / outcome | From the user request; otherwise broad overview |
+| Supplied-material baseline | Facts and claims already available |
+| Research gaps | Only facts needed to support the requested outcome |
+| External-source boundary | External factual enrichment allowed; supplied facts remain authoritative inputs |
| Output language | Match user input |
-| Target audience | Audience implied by the request; otherwise state a provisional general audience |
-| Research-facing communication intent | Open prose describing what the eventual presentation should accomplish; may combine several purposes |
-| Desired audience outcome | What the audience should know, understand, believe, decide, or do after the presentation |
-| Slug for files (`<topic_slug>`) | snake_case English identifier derived from topic |
-
-**Forbidden — itemized confirmation**: do NOT ask each row separately. One bundled clarifier or none.
+| Target audience / communication intent | Use what is already explicit; leave final confirmation to the main Strategist stage |
+| Research stem (`<research_slug>`) | `<topic_slug>_research`; choose another unused snake_case stem rather than overwrite an existing file |
-**Communication intent is not a pick-list.** You may mention inform / explain / persuade / decide / align / teach / report and account / mobilize / record and hand off as examples that help the user answer, but never ask them to select one label. Preserve multiple purposes plus their priority / sequence. This intake captures only the subset needed to aim research; main-pipeline Stage 1 confirms the full communication contract—audience, outcome, core message / ask, delivery context, artifact afterlife, and source-treatment intent—after the facts exist. Every editable Stage-1 prose field may remain blank after confirmation. Stage 2 confirms reading mode with the complete deck solution.
+Do not repeat the full main-pipeline confirmation here. Generate Step 4 still confirms the complete communication contract and deck solution after the factual inputs are ready.
---
-## Step 2: Gather via web search
-
-**Tools** — use the web search and web fetch tools the current IDE provides:
-
-| IDE | Web search | Web fetch |
-|---|---|---|
-| Claude Code | `WebSearch` | `WebFetch` |
-| Cursor / Codebuddy / VS Code + Copilot | provider-equivalent built-in | provider-equivalent built-in |
-| None available | — | fallback below |
+## Step 2: Gather factual sources
-**Fallback when no IDE web tools** — pause, ask the user for 2–4 authoritative URLs (Wikipedia / official site / institutional release), then fetch each:
+Use the web search and fetch tools supplied by the current IDE. If none are available, pause and ask the user for authoritative URLs covering the declared gaps, then fetch each with:
```bash
python3 ${SKILL_DIR}/scripts/source_to_md/web_to_md.py <URL>
```
-**Search strategy**:
-
| Phase | Action |
|---|---|
-| Landscape | One broad search; identify authoritative sources |
-| Deep fetch | Pull 2–4 highest-signal pages in full |
-| Targeted fill | Search for subtopics the deep fetch flagged |
-
-**Source priority**:
+| Orient | Search only far enough to map authoritative sources to the declared gaps |
+| Deep fetch | Read the highest-signal primary or authoritative pages in full |
+| Targeted fill | Search only for gaps still unsupported after those reads |
-| Tier | Source |
+| Priority | Source |
|---|---|
-| 1 | Wikipedia / Wikimedia Commons |
-| 2 | Official sites, institutional releases |
-| 3 | Reputable news / academic articles |
-| Avoid | Stock-aggregator watermarked images, social-media reposts without source |
+| 1 | Primary sources, official sites, institutional releases, standards, or original research |
+| 2 | Authoritative reference works and reputable academic sources |
+| 3 | Reputable reporting or analysis when primary evidence is unavailable |
+| Avoid | Unsourced reposts, unverifiable summaries, and stock-aggregator pages |
-**Stop condition**: stop when gathered material covers overview / history / key aspects / impact / sources with concrete facts and named entities. Endless searching produces noise.
+**Stop condition**: stop when every declared gap has enough sourced evidence for the Strategist to decide whether and how to include it. Do not expand into unrelated overview / history / outlook sections merely to make the research look complete.
---
-## Step 3: Save materials
+## Step 3: Save the factual supplement
-Three artifacts under `projects/`:
+Write two artifacts under `projects/`:
| Artifact | Path |
|---|---|
-| Research document | `projects/<topic_slug>.md` |
-| Fact provenance | `projects/<topic_slug>.facts.json` |
-| Image folder | `projects/<topic_slug>/` |
+| Research supplement | `projects/<research_slug>.md` |
+| Fact provenance | `projects/<research_slug>.facts.json` |
-**Hard rule — naming**: filename (without `.md`) and folder name MUST match. **Hard rule — location**: under `projects/`, never the repository root.
+**Hard rule — location and preservation**: write both files under `projects/`, never the repository root. Do not overwrite an existing user file; choose a new research stem instead. This stage creates no image folder.
-**Document structure** — begin with a compact `## Research Brief` carrying Target audience, Communication intent, and Desired audience outcome in open prose. Then let section layout follow the topic: person → biography / works / impact; technology → background / mechanism / applications / outlook; company → overview / products / market / culture. The file MUST end with a `## Sources` section listing the URLs used.
+Begin the research Markdown with a compact `## Research Brief` containing the supplied-material baseline, declared gaps, audience / intent already known, and requested outcome. Organize the body by gap, include concrete facts only, flag material conflicts, and end with `## Sources` listing every URL used.
-**Content density** — concrete facts (dates, names, numbers, quotes). Skip filler prose; the Strategist composes final slide copy.
-
-**Fact provenance** — write every externally sourced, verifiable claim that may enter the deck to `<topic_slug>.facts.json` with a stable sequential ID, especially quantitative, date, ranking, attribution, and named-entity claims. Do not put invented demonstration values in this file; Strategist marks those as `scenario` later. When research yields no external claims, still write the schema with an empty `facts` array.
+Write every externally sourced claim that may enter the deck to `<research_slug>.facts.json` with a stable sequential ID, especially quantitative, date, ranking, attribution, and named-entity claims. Do not include user-supplied claims or invented scenario values. When no external claim is retained, write the schema with an empty `facts` array.
```json
{
@@ -112,38 +99,24 @@ Three artifacts under `projects/`:
}
```
-IDs are immutable within the file. If a claim is corrected, update its value/source under the same ID; if a claim is removed, do not silently reuse its ID for a different fact. The research Markdown and `facts.json` must agree.
-
-**Images**:
-
-| Decision | Rule |
-|---|---|
-| Quantity | Cover the deck's likely scenes (cover, key aspects, key entities); the Strategist decides the final cut |
-| Resolution | Prefer originals. Wikimedia: strip `/thumb/` and the `Npx-` prefix from the URL to get full resolution |
-| License | Wikimedia / public-domain / CC-licensed; avoid stock-aggregator watermarks and unsourced uploads |
-| Filename | descriptive English snake_case (`joe_hisaishi_concert.jpg`, not `image1.jpg`) |
-
-```bash
-mkdir -p "projects/<topic_slug>"
-curl -L -o "projects/<topic_slug>/<descriptive_name>.<ext>" "<image_url>"
-```
+IDs are immutable within the file. Correct a claim under the same ID; never reuse a removed ID for a different fact. The research Markdown and provenance file must agree.
---
## Hand-off
-Output a checkpoint, then continue with the main pipeline. The artifacts feed directly into Step 2's `import-sources`:
+Import the research supplement and provenance alongside any user-supplied sources in Generate Step 2:
-The Research Brief is evidence-facing context, not a locked presentation contract. Strategist reads it when preparing Stage 1, then confirms / edits the full contract with the user before choosing narrative mode, template reuse, or visual direction.
+```bash
+python3 ${SKILL_DIR}/scripts/project_manager.py import-sources projects/<project_name> [<source_paths...>] projects/<research_slug>.md projects/<research_slug>.facts.json --move
+```
+
+The Research Brief remains evidence-facing context, not a locked presentation contract. Strategist reads all imported source material, then confirms the complete contract and decides the content, page roster, and image resource plan. Generate Step 5 acquires only the selected image rows after that confirmation.
```markdown
## ✅ Topic Research Complete
-- [x] Document: `projects/<topic_slug>.md` (N sections)
-- [x] Facts: `projects/<topic_slug>.facts.json` (N external facts)
-- [x] Images: `projects/<topic_slug>/` (N files)
-- [ ] **Next**: [`generate-pptx`](../generate-pptx.md) Step 2 →
- `project_manager.py init <project_name> --format <format>`
- `project_manager.py import-sources projects/<project_name> projects/<topic_slug>.md projects/<topic_slug>.facts.json projects/<topic_slug>/*.* --move`
+- [x] Research supplement: `projects/<research_slug>.md` (N declared gaps covered)
+- [x] Fact provenance: `projects/<research_slug>.facts.json` (N external facts)
+- [x] No images acquired before Strategist confirmation
+- [ ] **Next**: return to [`generate-pptx`](../generate-pptx.md) Step 1, then import all source artifacts in Step 2
```
-
-`<project_name>` is the user's chosen project identifier (typically `<format>_<topic_slug>`, e.g. `ppt169_joe_hisaishi`); `--move` removes the research artifacts from `projects/<topic_slug>` after they are imported and deletes the folder itself once it is empty.