| 1 | --- |
| 2 | description: Generate source-intake stage that fills externally verifiable factual gaps before planning or direct SVG authoring. |
| 3 | --- |
| 4 | |
| 5 | # Topic Research Stage |
| 6 | |
| 7 | > Factual preparation inside the active Generate profile's source intake. |
| 8 | > Default Generate hands its output to Strategist; Quick Generate's main agent |
| 9 | > consumes the same output. Run immediately for topic-only input, or after |
| 10 | > supplied material is converted and read when it leaves planning-critical |
| 11 | > factual gaps. Output is a research supplement plus stable fact provenance for |
| 12 | > project import. |
| 13 | |
| 14 | This stage supplies facts needed to build the requested deck. It does not select, |
| 15 | download, or generate images. Default Generate resolves image selection in the |
| 16 | final Strategist plan and acquires AI / web / slice assets after confirmation; |
| 17 | Quick Generate resolves and acquires them later in its resource-preparation |
| 18 | phase without adding a confirmation gate. |
| 19 | |
| 20 | ## When to Run |
| 21 | |
| 22 | | Material state | Action | |
| 23 | |---|---| |
| 24 | | Topic or requirements with no supporting facts | Research the factual baseline needed for the requested outcome | |
| 25 | | Supplied files or chat content cover only part of the requested outcome | After conversion and reading, research only the identified externally verifiable gaps | |
| 26 | | Supplied material already supports the requested outcome | Skip this stage and continue the active Generate profile's source preparation | |
| 27 | | User requires a closed corpus, source-only transformation, or no external enrichment | Skip this stage and keep planning within supplied material | |
| 28 | |
| 29 | **Sufficiency test**: a gap exists when the active content owner 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. |
| 30 | |
| 31 | **Hard rule — preserve supplied facts**: supplement the user's material; never |
| 32 | silently replace it. Record a material source conflict in the research output |
| 33 | for the active content owner instead of choosing a different claim without |
| 34 | disclosure. Do not research omissions outside the requested scope. |
| 35 | |
| 36 | --- |
| 37 | |
| 38 | ## Step 1: Define the gap brief |
| 39 | |
| 40 | **Clarification boundary**: Default Generate bundles only genuinely missing |
| 41 | scope or research-boundary decisions into one clarifier. Quick Generate applies |
| 42 | the defaults below and continues without interaction; stop only when a required |
| 43 | permission or safety boundary cannot be inferred responsibly. Skip clarification |
| 44 | when the request and supplied material are already clear. |
| 45 | |
| 46 | | Item | Default if unspecified | |
| 47 | |---|---| |
| 48 | | Topic | From the user request | |
| 49 | | Requested scope / outcome | From the user request; otherwise broad overview | |
| 50 | | Supplied-material baseline | Facts and claims already available | |
| 51 | | Research gaps | Only facts needed to support the requested outcome | |
| 52 | | External-source boundary | External factual enrichment allowed; supplied facts remain authoritative inputs | |
| 53 | | Output language | Match user input | |
| 54 | | Target audience / communication intent | Use what is explicit; Default leaves final confirmation to Strategist, while Quick resolves routine gaps in active context | |
| 55 | | Research stem (`<research_slug>`) | `<topic_slug>_research`; choose another unused snake_case stem rather than overwrite an existing file | |
| 56 | |
| 57 | Do not repeat the full default-pipeline confirmation here. Default Generate |
| 58 | confirms the complete communication contract in Step 4; Quick Generate adds no |
| 59 | confirmation stage. |
| 60 | |
| 61 | --- |
| 62 | |
| 63 | ## Execution Context |
| 64 | |
| 65 | **Default — isolated research when available**: The main agent owns the sufficiency decision and gap brief. When the current AI editor supports and permits an isolated subagent with web/fetch access and write access to the declared outputs, dispatch exactly one research worker. Otherwise the main agent runs Steps 2–3 locally. |
| 66 | |
| 67 | | Actor | Contract | |
| 68 | |---|---| |
| 69 | | Main agent | Supply the topic/outcome, baseline or relevant source paths, declared gaps, output language, two exact unused output paths, and this stage's absolute path as execution authority; use paths instead of pasting source bodies when possible | |
| 70 | | Research worker | Read the supplied stage file completely, then follow Steps 2–3 using the brief and declared source paths as its baseline; limit project writes to the two output artifacts; acquire no images and make no deck-planning or design decisions | |
| 71 | |
| 72 | **Hard rule — isolate retrieval, not research**: Raw page content and fetch transcripts stay in the worker context. The 250-word limit applies only to its chat receipt: return `status`, exact artifact paths, covered/unresolved gap counts, external-fact count, and material conflicts. It does not cap or replace the two artifacts. After validation and import, the active content owner reads the complete imported research supplement and fact-provenance JSON into the main context before planning or direct SVG authoring; never use the receipt or validation summary as content. |
| 73 | |
| 74 | **Validation**: Before import, the main agent verifies both exact files exist, the Markdown contains `## Research Brief` and `## Sources`, the JSON parses with schema `ppt-master.fact-provenance.v1` and unique sequential IDs, and the two files agree. Return an invalid pair to the research worker for owning-artifact repair; use main-context web research only when isolated execution is unavailable. |
| 75 | |
| 76 | --- |
| 77 | |
| 78 | ## Step 2: Gather factual sources |
| 79 | |
| 80 | Use the web search and fetch tools available in the active research context. An isolated worker without them returns `blocked: web-tools-unavailable`. If no usable research context has search/fetch tools, the main agent pauses and asks the user for authoritative URLs covering the declared gaps, then fetches each with: |
| 81 | |
| 82 | ```bash |
| 83 | python3 ${SKILL_DIR}/scripts/source_to_md/web_to_md.py <URL> |
| 84 | ``` |
| 85 | |
| 86 | | Phase | Action | |
| 87 | |---|---| |
| 88 | | Orient | Search only far enough to map authoritative sources to the declared gaps | |
| 89 | | Deep fetch | Read the highest-signal primary or authoritative pages in full | |
| 90 | | Targeted fill | Search only for gaps still unsupported after those reads | |
| 91 | |
| 92 | | Priority | Source | |
| 93 | |---|---| |
| 94 | | 1 | Primary sources, official sites, institutional releases, standards, or original research | |
| 95 | | 2 | Authoritative reference works and reputable academic sources | |
| 96 | | 3 | Reputable reporting or analysis when primary evidence is unavailable | |
| 97 | | Avoid | Unsourced reposts, unverifiable summaries, and stock-aggregator pages | |
| 98 | |
| 99 | **Stop condition**: stop when every declared gap has enough sourced evidence for |
| 100 | the active content owner to decide whether and how to include it. Do not expand |
| 101 | into unrelated overview / history / outlook sections merely to make the |
| 102 | research look complete. |
| 103 | |
| 104 | --- |
| 105 | |
| 106 | ## Step 3: Save the factual supplement |
| 107 | |
| 108 | Write two artifacts under `projects/`: |
| 109 | |
| 110 | | Artifact | Path | |
| 111 | |---|---| |
| 112 | | Research supplement | `projects/<research_slug>.md` | |
| 113 | | Fact provenance | `projects/<research_slug>.facts.json` | |
| 114 | |
| 115 | **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. |
| 116 | |
| 117 | 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. |
| 118 | |
| 119 | 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. |
| 120 | |
| 121 | ```json |
| 122 | { |
| 123 | "schema": "ppt-master.fact-provenance.v1", |
| 124 | "topic": "<topic>", |
| 125 | "facts": [ |
| 126 | { |
| 127 | "fact_id": "F001", |
| 128 | "claim": "One concise, presentation-ready factual claim", |
| 129 | "source_title": "Authoritative page title", |
| 130 | "source_url": "https://example.org/source", |
| 131 | "classification": "external", |
| 132 | "retrieved_at": "YYYY-MM-DD" |
| 133 | } |
| 134 | ] |
| 135 | } |
| 136 | ``` |
| 137 | |
| 138 | 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. |
| 139 | |
| 140 | --- |
| 141 | |
| 142 | ## Hand-off |
| 143 | |
| 144 | Import the research supplement and provenance alongside any user-supplied |
| 145 | sources through the active profile's source intake: |
| 146 | |
| 147 | ```bash |
| 148 | python3 ${SKILL_DIR}/scripts/project_manager.py import-sources projects/<project_name> [<source_paths...>] projects/<research_slug>.md projects/<research_slug>.facts.json |
| 149 | ``` |
| 150 | |
| 151 | The imported pair remains evidence-facing context, not a locked presentation |
| 152 | contract. Default Generate has Strategist read both files completely before |
| 153 | confirmation and use them to select the content, page roster, and image resource |
| 154 | plan. Quick Generate has the current agent read both completely before its |
| 155 | active-context content, design, and resource decisions. |
| 156 | |
| 157 | ```markdown |
| 158 | ## ✅ Topic Research Complete |
| 159 | - [x] Research execution: <isolated worker | main-context fallback> |
| 160 | - [x] Research supplement: `projects/<research_slug>.md` (N declared gaps covered) |
| 161 | - [x] Fact provenance: `projects/<research_slug>.facts.json` (N external facts) |
| 162 | - [x] Artifact contract validated: `## Research Brief`, `## Sources`, `ppt-master.fact-provenance.v1`, unique sequential IDs, and Markdown/JSON agreement |
| 163 | - [x] No images acquired inside this factual-research stage |
| 164 | - [ ] **Next**: Default returns to [`generate-pptx`](../generate-pptx.md) Step 2; Quick returns to [`quick-generate`](../profiles/quick-generate.md) §2. Import all source artifacts, then fully read the imported research pair before planning or direct SVG authoring |
| 165 | ``` |
| 166 |