chart-storytelling

Chart Storytelling

Organize evidence with charts, use the preset chapter schema to turn data analysis into an HTML story or Web-PPT, first produce a plan.mdthat can be reused across deliverables, then generate the specific deliverable via the corresponding build module. Core architecture:Shared narrative design (Phase 1-3) + per-deliverable Build execution (Phase 4)。

Core Definition

Data Story = Data(insight evidence) + Narrative(cognitive path) + Visuals(visual presentation)

Data storytelling is not "visualizing analysis results"; it is combining these three elements into a product that lets a specific audience understand faster and decide more easily.

A true data story must simultaneously answer:

1. What question does the reader care about most?
2. Which evidence is sufficient to answer this question?
3. How should the page be ordered so that the reader can understand it with almost no "self-translation"?

---

Architecture Overview

Phase 1-3（共享叙事核心）
  理解 → 数据分析 → 叙事设计
           ↓
       plan.md
  故事元信息 + 证据骨架 + 章节基础结构 + 样式选择
           ↓
  用户确认 plan.md
           ↓
  Phase 4: Build（按目标产物加载对应 build 模块）
      ↓
build-html/ | build-ppt/
      ↓
    具体产物

---

Runtime Environment

Python 3.10+ is used for the bundled standard-library scripts, and Node.js is used for JavaScript syntax validation; the browser must be able to access the public unpkg CDN. The current Agent is responsible for reading data, reasoning, and generating VSeed configurations, and does not need the VisActor-hosted model service. Regular charts use VSeed 0.6.5, VChart 2.1.7, and VTable 1.26.8; HTML animations use GSAP 3.15.0. Image generation is an optional host capability; when unavailable, follow the Plan and disclose the fallback. Web-PPT outputs HTML, not .pptx。

runtime/ denotes the user project's artifact directory; for evaluation or when unified output is required, use outputs/runtime/。$SKILL_DIR must point to the complete installed Skill directory. Do not rewrite the installed Skill.

If the user has explicitly authorized end-to-end generation, proceed directly to Build after recording assumptions and the plan; otherwise, make one confirmation during the planning phase.

Workflow

Phase 1: Understand and Define

Gather the following information in a single focused round of questions:

1. Audience — Who are the readers? What should they understand and what decisions should they make after reading?
2. Core Question — Which question is this story trying to answer?
3. Overall Style - In what style (visual/tone) should this story be presented?
4. Available Data — What existing data, analysis outputs, and images are available?
5. Constraints — Publishing scenario, time range

If key information is missing but the risk is controllable, explicitly state the assumptions and continue.

Phase 2: Data Analysis and Insight Discovery

Analyze the data first, then design the story. This is the most critical step.

1. Inventory the inputs — tables, screenshots, reports, images, existing copy
2. Check reliability — time range, granularity, sample size, missing values, changes in definitions
3. Find 3-5 findings, and label the insight type:
   • Trend: something is rising, falling, or changing periodically
   • Anomaly: Something is unexpectedly high, low, or different
   • Contrast: Two entities differ in a meaningful way
   • Composition: What the way the parts make up the whole reveals
   • Correlation: Two things change together (or in opposite directions)
4. Rank by importance — The #1 finding becomes the core conflict of the story
5. Compute Key Numbers — The key values that the narrative text will cite; at this point compute them precisely from the data and record the variable names for later writing into plan.md. In the final presentation, number units are also part of readability; do not mechanically translate the original field units or suffix. Instead, choose natural units according to the target language, numerical magnitude, and reader habits, and convert the values and precision accordingly.

Save the analyzed data as runtime/dataset_map.json(reference name → record array), preserving the inputs and computation process that allow recomputation. You may use Python/DataFrame tools provided by the host, but do not rely on persistent memory across calls. plan.md stores only data reference names and does not embed the data again.

If the user's claim does not match the data: point it out directly and offer a more defensible story angle.

Not only verify the numbers, but also verify whether they are sufficient to support the conclusion. Choose the analysis method according to the type of judgment, and retain the applicable comparison basis and verifiable calculation basis in the existing Evidence / Key Numbers.source . When the evidence is insufficient, narrow or withdraw the judgment; do not fill the gap with narrative. The strength of expression in the title, summary, and body must not exceed the scope supported by the evidence.

Phase 3: Narrative design

3a: Choose the story arc

All data stories follow the Context → Conflict → Resolution → Ending structure. Choose a specific arc pattern according to the dominant insight type:

Insight type	Arc Pattern
A problem with an identifiable cause	Situation-Complication-Resolution (SCR)
A surprising/counterintuitive finding	Hook-Tension-Climax-Resolution (Dramatic)
A number that needs to be broken down	"So What?" progressive drill-down (Drill-Down)
A meaningful difference between entities	Contrast/comparison (Versus)
Change over time	Journey/transformation (Timeline)

→ Read story-arc-patterns.md to get the complete chapter structure, transition examples, and common mistakes for each pattern.

3b: Choose a Section Pattern for each chapter

A Section Pattern is the unit of narrative choice at the chapter level. Choose one Pattern for each chapter: first decide what cognitive task this chapter is to accomplish, and which semantic inputs the planning stage must prepare clearly.

Currently 8 Section Patterns are supported.

Pattern	Narrative purpose	Applicable scenarios	Inapplicable scenarios	What must be decided in the planning stage
hero-impact	Establish a strong visual anchor with a single hero number or a strong background image atmosphere	hook; key turning points, rhythm peaks, or strong closings under PPT goals; in HTML story, apart from the hook, use only cautiously in special feature/editorial scenarios	Openings with only a title/lead-in, regular mid-section analysis chapters, reading the main chart's evidence, KPI groups, ordinary closing chapters	What the main anchor is: a hero number / hero ratio / hero difference / hero magnitude of change, or an already-planned hero_background_image; if it is a numeric anchor, explain how the number is read and its mnemonic point; if it is an image anchor, explain the narrative role carried by the background atmosphere
cover-intro	Bring the story in with a restrained, steady opening	hook chapter; you need to first establish problem awareness, stakes, or why-now before entering the evidence chapter	mid-section analysis chapters, closing chapters, and openings that need the main number as the primary visual anchor	SectionIntro required;LeadMeta optional, used for cover-level supporting information
scrollytelling	progressively advance understanding of the same main chart	HTML story or Web-PPT where discrete steps are needed to control pacing, and each step can correspond to a state, filter, annotation, or highlight change in the main chart	single static explanation, sections without progressive visual advancement, sequential interpretation of multiple independent charts	step progression、Charts main chart, chart state changes corresponding to each step
chart-narrative	complete one Claim with chart evidence	regular analysis chapters, directly interpreting one main chart; or sequentially unfolding 2-3 charts that serve the same Claim chart	chapters that need multi-step visual advancement, or that are primarily side-by-side comparisons	main chart, main conclusion, and corresponding evidence; if it is a multi-chart sequential analysis, clarify the sub-question order for each chart, and there is only one primary
baseline-kpis	establish baseline coordinates with side-by-side KPIs	early sections need to first present 2-4 side-by-side key metrics so readers first know how big the pie is or where the current level is	hook chapters, sections that need a main chart to carry evidence, need trend/structure/distribution/gap shapes, need complex argumentation or causal progression, or have only a single main number	which metrics appear together, sorting method, how to read each metric; if thematic symbols are needed, describe only their semantic role
comparison	side-by-side comparison of differences	A/B comparison, before/after comparison, between-group differences, or clearly comparison-led perspective switches of definitions/ledgers/metrics	sections with only a single object and single conclusion, or multi-chart chapters that are merely a sequential analysis chain	comparison object or comparison perspective, comparison dimensions, conclusion focus
timeline	organize understanding in chronological order	historical evolution, phase changes, milestones; or a single main chart that needs time anchors to assist reading	static structural analysis unrelated to time, trend explanations without clear time nodes	at least 3 time nodes, time segments, key nodes and phase significance; if combined with a single chart, compress into 3-5 time anchors, and write a short explanation for each node
action	give a clear next step	closing action recommendations, decision recommendations, with 2-5 action items	sections still explaining evidence and not yet converging, or with only one action point	action targets, priorities, and action rationale

scrollytelling rendered in HTML story as sticky chart + steps; rendered in Web-PPT as a single scroll-scene slide, where scrolling / keyboard first advances the steps inside the slide, then turns the page after reaching the boundary. When choosing this pattern, the planning stage must first determine step progression, and must fill in Charts main chart;Steps cannot replace Charts. In the Build stage, do not temporarily upgrade a regular chart-narrative to scrolling. Scrollytelling main charts may only use line / area / column / columnPercent / bar / barPercent / columnParallel / barParallel / dualAxis, and must not use heatmap and other dense matrices or single static charts. For specific step patterns and writing methods, see pattern-scrollytelling-plan.md。

if you choose timeline and want it displayed in combination with a single image, the planning stage must first confirm that it can be compressed into 3–5 key nodes, and that each node is only a time anchor on the main image, not a second body-text column. The specific top/bottom or left/right layout is decided by the HTML Build stage.

The final chapter of a Web-PPT must have a clear closing intent: a final judgment, next steps, a memorable number, or an atmospheric wrap-up. Do not end only with new evidence, chart explanations, or methodological notes.

The planning stage must also comply with:

• resolution answer the core question and close the evidence;ending leave a final judgment, direction, warning, or open question.
• If multiple images are a side-by-side comparison, use comparison; if they are step-by-step state progression of the same main image, use scrollytelling。
• The Hook chapter may only use cover-intro or hero-impact；chart-narrative、baseline-kpis、comparison is not used as a hook. For an opening with a main number or strong background image, use hero-impact; to establish problem awareness, stakes, or why-now, use cover-intro。
• hero-impact only establishes a single main-number anchor or a strong background-image atmospheric anchor, and is not responsible for main-image evidence reading, KPI groups, or ordinary endings. Under the HTML story goal, it usually should not be chosen in the middle section except for the hook; under the PPT goal, use it only when that chapter itself is the rhythm peak of key numbers or strong background atmosphere.
• cover-intro is only used for Role: hook, must fill in SectionIntro, optionally LeadMeta, and does not carry main images, KPI groups, or evidence bars.
• baseline-kpis is only responsible for establishing a baseline of parallel metrics; it is not a dashboard, and it should not be placed side by side with a main image to form a single chapter.

3c: Choose Presentation Mode and Style Preset

1. First write Story Meta.presentation_mode, which can only be:

• editorial: data reporting / analytical report / decision brief. Evidence and text take priority, and assets have low presence;hero_background_image is used only when context truly needs to be established, and must be lightweight, restrained, and low-drama.
• feature: special topics / sports / entertainment / games / film / IP / city events and other strong narrative entry points. They require first-screen visuals with stronger thematic identity and clearer scroll guidance; prioritize planning hero_background_image or an opener motif, but must not sacrifice chart readability or evidence credibility.

1. Then read STYLE_PRESETS.md, and choose one according to the preset selection matrix Style Preset。

A Preset is a base style family: it only defines the base style direction, default color anchors, chart palette, and suitable asset cues; it is not a complete brand theme, scene theme, or event-stage theme. In the Plan stage, write only the preset name, and transcribe the preset summary into Story Visual Identity and each asset's visual_brief; do not copy implementation fields, style snippets, font stacks, or other internal details from the preset details. Page styles and chart themes are resolved by the Build stage according to Style Preset name.

1. After selecting the preset, then determine whether ### Style Overrides。

Style Overrides are explicit theme patches added to the preset base, not a way to make feature automatically cooler or flashier. Omit by default.

Natural-language theme constraints also count as explicit constraints. When the user specifies a concrete scene, theme, IP, event, city, tournament, or brand temperament and requests a feature-oriented presentation, first determine which layer it affects:

• If it only affects asset content, motif, opening image subject, or visual_brief, write it into Story Visual Identity / Asset Registry, and do not write Style Overrides。
• If it needs to affect the full-page stage background, accent colors, or chart palette, then write minimal Style Overrides.
• If the user only says "cooler", "younger", or "more premium" without a concrete visual world, choose the closest preset and do not write overrides.

Only when you decide to fill in ### Style Overrides do you read style-overrides.md. Do not write internal classes, freeform style rules, layout fields, or intent words. When there is no explicit requirement, omit the entire ### Style Overrides block.

3d: Plan visual assets (Asset Director)

plan.md is the director's script for the final work. Do not generate final SVG / images here, and do not bind shared component names from the build layer; here you only define this story's visual identity, asset strategy, generatable assets, and why each chapter needs those assets.

Assets can be decorative, but they must not be random decoration. Decorative assets must serve the Story Visual Identity: reinforcing theme, domain, IP character, sense of era, sense of space, or narrative memory points. They must not compete with titles, key numbers, chart evidence, and takeaways.

The Asset Registry only records assets that will actually enter permitted placement positions. Before declaring an asset, all of the following must be satisfied:

• purpose State the narrative task it serves: identity recognition, semantic framing, data-adjacent memory points, or emphasis at a specific hosting position.
• visual_brief Describe the thematic language, form, color constraints, and hosting method; do not just write "generic decoration".
• The asset has a legal placement position and an expected chapter hosting position; if there is no legal placement position, do not declare it.
• The asset does not repeat geometric shapes, ordering relationships, trend evidence, or annotation functions already expressed by charts; chart evidence takes priority.
• The same asset language obeys the Story Visual Identity and Style Preset; an individual chapter must not invent a new visual world.

Control asset presence according to Story Meta.presentation_mode :

• editorial: assets serve only as a supporting layer;hero_background_image must be lightweight and low-drama, leaning toward texture, atmosphere, or abstract context.
• feature: prioritize evaluating hero_background_image or opener motif; the opening visual may have stronger subject recognition, scene, and thematic feel, but still cannot replace chart evidence.

## Assets must contain two sub-blocks:

Story Visual Identity

• theme_subject: the thematic object or domain of this story, for example global carbon ledger、wizard merchandise sales、space telescope survey
• visual_language: the overall visual language, for example "editorial-style technical line art", "cinematic archive collage", "museum archive"
• recurring_motifs: 1-3 motifs that run through the whole text, for example orbital lines, ledger grid lines, magic parchment edges
• avoid: visual directions that must explicitly not appear, for example generic clip art, overly strong neon, irrelevant mascots

Asset Registry

Each asset uses the following fields:

• id: machine-readable id, written as the list title, for example - `carbon_ledger_grid`
• source: generated | user-provided, optional; when omitted it is equivalent to generated
• media_hint: svg | image
• purpose: why it is needed, and which story task it serves
• visual_brief: the visual brief used when generating the asset during the build stage
• fallback: remove | gradient | text-only

source: generated and media_hint: image is a formal build artifact request, not an optional decoration suggestion. It must have a concrete purpose、visual_brief、fallback, and be referenced by at least one chapter's SectionVisual.assets placement. The Build stage must either generate it through the target artifact's official generated-image path, or explicitly execute the fallback declared in the plan; it must not be silently replaced with an unrelated hand-made placeholder image.

Do not declare assets that will not be used by a chapter. Each registry asset must be referenced by at least one chapter's SectionVisual.assets .

When using an asset within a chapter, write in SectionVisual :

- assets:
  - placement: primary_image
    asset: pilot_evidence_wall
    usage: "作为本章主图证据，展示试点现场已经形成可路演、可复盘的真实材料。"

Allowed placement positions:

• hero_background_image: As hero-impact strong opening background image;editorial light auxiliary support,feature allows stronger subject recognition
• opener_motif_background: As cover-intro weak opener motif background layer
• primary_image: As a first-class main image evidence for PPT / image evidence pages, not decoration
• evidence_image: As one evidence image in a PPT / multi-image evidence grid
• visual_artifact: As an in-page evidence object for PPT / generated SVG mechanism relationships, process structures, or product states
• takeaway_accent: As weak decoration or corner marker for takeaway / highlight
• kpi_lead_icon: As a lightweight symbol for a lead KPI card
• action_lead_asset: As a weak asset at the bottom/corner of an action lead card, rather than a small icon next to the title

Do not use placement to express material provenance.source is responsible for provenance,placement is responsible for page role.

• Under the HTML target,evidence_image if it carries factual image evidence such as on-site photos, interface screenshots, report page screenshots, etc., it should use source: user-provided. Generated images cannot impersonate documentary evidence.
• Under the PPT target,primary_image and evidence_image are both first-class image materials; the difference is only single main image vs multi-image evidence group, not material tier.

visual_artifact can only serve as SectionVisual.assets[].placement, do not write visual_artifact as Pattern, chapter type, section type, or SectionVisual.structure page plan. When a mechanism diagram is needed,SectionVisual.structure only describes that this chapter needs a non-data evidence object and the reading task it serves; which type of page it lands on in the target artifact is decided by the Build stage.

visual_artifact 's visual_brief only describes the mechanism relationship, process structure, product state, or scene collage to be drawn. The material itself does not write page titles, conclusion sentences, footnotes, or body paragraphs; these are left to chapter Title、Claim、SectionIntro、SectionVisual.focus or visible copy in the Build stage.

The Plan stage does not generate SVG / image files; it only defines material direction, material list, and chapter usage relationships. Specific material files are handled by the Build stage.

3e: Write the plan.md structured outline

First produce a complete plan.md draft (see the template below), then after one Title Pass show it to the user for confirmation, then proceed to Phase 4.

plan.md is the structured summary of all narrative decisions in Phase 3, and it also serves two roles:

1. User confirmation point: shown to the user at the end of Phase 3
2. Build authoring input: Phase 4 generates the specific artifact based on it

Build input here refers to the "director's script read during writing and orchestration in the build stage." The Build stage solidifies decisions such as chapter order, titles, body text, chart references, asset usage, and Methodology into the generation logic of the target artifact.

The top-level structure of plan.md is fixed as:

• ## Story Meta
• ### Style Overrides(optional; fill in only when allowed by 3c)
• ## Evidence Backbone
  • ### Data References
  • ### Key Numbers
  • ### Methodology
• ## Chapter Outline
• ## Story Breaks(optional)
• ## Assets

The following is a minimal plan template Do not treat a complete case as the only standard answer. The snippets are only used to illustrate field structure, hierarchy relationships, and minimal legal writing; they do not prescribe a specific industry, tone, writing style, or chapter content order.

# Story Plan

## Story Meta
- **Title**:
- **Core Question**:
- **Core Takeaway**:
- **Arc Pattern**:
- **Style Preset**:
- **presentation_mode**: editorial
- **Audience**:
- **Language**:

## Evidence Backbone

### Data References
- `dataset_id`: 数据内容与字段说明

### Key Numbers
- `metric_name` = value
  - meaning:
  - source:

### Methodology
- **Data Source**:
- **Time Range**:
- **Caveats**:

## Chapter Outline

首章 `Title` 可省略；默认直接沿用 `Story Meta.Title`。只有首章需要不同入口句时才显式填写。`Ch2+` 仍必须显式提供 `Title`。

### ChN
- **Role**:
- **Pattern**:
- **Title**: （短标题；完整解释写入 Claim）
- **Intent**:
- **Claim**:
- **Evidence**:
  - refs: [`dataset_id`]
  - key_numbers: [`metric_name`]
- **SectionVisual**:
  - structure:
  - focus:
  - assets: （仅当该章节需要使用 Asset Registry 中的资产时填写）
    - placement: primary_image
      asset: carbon_ledger_wall
      usage: "作为本章主图证据；如果只是弱装饰才使用 takeaway_accent。"
- **LeadMeta**: （可选；无标签封面信息，仅 `cover-intro` 常用）
- **SectionIntro**: （可选；读者可见正文。`cover-intro` 必填）
- **Charts**: （可选；需要普通统计图表证据视觉时，先读 `references/chart-contract.md`）
- **Transition**:

## Story Breaks

仅当目标产物包含 PPT，且故事需要换幕、转向或停顿时填写；不是每章之间都要加。`Transition` 是章节内 handoff 文案，`Story Breaks` 才是可被 PPT Build 渲染成独立过渡页的节奏标记。非 PPT 产物默认忽略该区块。

- after: Ch2
  type: pivot
  title: 从总量，转向结构
  intent: 把读者从总体平台判断带到部门差异分析
  cue: 不是一年峰值，而是新平台

## Assets

### Story Visual Identity
theme_subject: "..."
visual_language: "..."
recurring_motifs:
  - "..."
avoid:
  - "..."

### Asset Registry
- `asset_id`
  - media_hint: svg
  - purpose: "..."
  - visual_brief: "..."
  - fallback: remove

In addition to the template, the following must also be observed:

• Every chapter must satisfy the basic structure in the template:Role、Pattern、Intent、Claim、Evidence、SectionVisual, and fill in as needed Title、SectionIntro、Charts、Transition。
• Role The vocabulary is fixed as hook / context / conflict / deep-dive / resolution / ending
• Charts is evidence visual, not a page asset system. Before writing any Charts , you must first read chart-contract.md; currently only ordinary statistical charts are supported, and they must be bound to dataRef，renderer fixed as standard-chart。
• For long table line / area, by default do not write detail: the classification field that determines each trend line must be written as color; only when color series already exists may another field that genuinely has auxiliary display significance use detail. Derived calculations should first produce data fields, and do not treat detail as a calculation channel.
• The PPT target also uses the same canonical Charts contract. As long as the plan requires chart pages, the chart id should use a backtick entry (recommended chN-chartM), and provide dataRef / renderer / chartType / dimensions / measures, where renderer may only be written as standard-chart. Do not write free-form chartId:、fields:, and do not use non-contract chart types such as combo-line、horizontal-bar ; local assembly will reject unparseable or incomplete chart contracts.
• scrollytelling The section must simultaneously contain Steps and Charts；Steps to describe the state change, andCharts to provide the main-chart evidence carrier. For step mode see pattern-scrollytelling-plan.md, for the chart progression contract see chart-contract.md
• Story Breaks is an optional PPT-only presentation pacing layer, not a chapter; it only expresses act changes, turns, or pauses, and does not carry Evidence / Claim / Charts. Non-PPT outputs ignore it by default
• Story Breaks.type Only divider / pivot / pause / recap；title is allowed to be a visible transition page title,intent is internal pacing description,cue is an optional visible subtitle

Title Contract and Title Pass

A title is not a Claim.Title is the final title that readers will directly see, not an analysis note, an internal review note, or the insight pasted verbatim into the title slot.

• Story Meta.Title is the story-level canonical title, used for the story-level headline.
• By default, the first chapter title follows Story Meta.Title; only when the first chapter needs a separate entry sentence should you explicitly fill in Ch1.Title。
• Ch2+ are the canonical titles of each chapter, and must be directly usable as the visible titles of HTML / Doc / PPT. Title of
• ### ChN only carries the chapter number and structural positioning, and does not carry a natural-language title.
• chapter Title must be short, single-focus, and directly displayable; it carries only one object + one judgment, question, or action direction.
• An opening title can be more like a story entry sentence, used to establish problem awareness, tension, a sense of scale, or a story entry; ordinary chapter titles should preferentially directly express a judgment, change, contrast, turning point, or question.
• Reasons, evidence, number elaboration, and full explanations go into Claim、SectionIntro、Transition, chart titles, or annotations; do not stuff these responsibilities back into Title。
• If the title reads like an analysis summary, or the story-style phrasing introduces ambiguity, it should be shortened and reverted to a more direct title.
• If lightweight emphasis is needed in continuous copy, you may directly use Markdown **...** to wrap keywords or very short conclusions; do not overuse bold on whole sentences.

In plan.md after the draft has been fully written andClaim / Intent / Evidence / SectionVisual has stabilized, run Title Pass：

• separately once: it may only modify Story Meta.Title and chapter visible titles; do not write back to Claim、Intent、Evidence、Transition。
• Inputs include at least:Audience、Style Preset、Core Takeaway、chapter Role、Pattern, current Title、Claim、Intent。
• The goal is not to retain as much information as possible, but to polish the title into a final title that can be directly displayed; assume Claim will exist in full, so the title does not bear the responsibility of explanation.
• If the title is already short enough, single-focused, and directly presentable, keep it as is; do not change it just for the sake of changing.
• There are only four common actions: remove explanations, remove causality, remove secondary qualifiers, and compress long viewpoint sentences into a single judgment / question / action direction.

3f: Check and confirm plan.md

Before entering Build, first check whether plan.md meets the following requirements:

• has been validated with scripts/validate_story_plan.py under the current skill root directory; if it fails, fix the plan first, then regenerate / re-review, and do not enter Build plan.md; if it fails, fix the plan first, then regenerate / re-review; do not proceed to Build
• Story Meta.Title and the visible chapter titles have gone through Title Pass and are suitable as direct display titles for HTML / PPT
• Key Numbers exactly match the data, and narrative citations have source annotations; number display units fit the target language and magnitude for readability, without mechanically retaining unsuitable original suffixes
• Methodology fully includes Data Source / Time Range / Caveats
• Story Meta / Evidence Backbone / Chapter Outline / Story Breaks / Assets is structurally complete with stable field naming; when Story Breaks is not used, that block may be omitted
• if the chapter includes Charts, the general statistical chart contract has been checked according to chart-contract.md , and renderer is standard-chart
• each chapter's Title / Intent / Claim / Transition / SectionVisual.focus / Charts[*] semantically serves the same main theme; do not discuss multiple focuses in one chapter or switch the analysis object mid-chapter without explanation
• Transition the handoff to the next chapter's main focus is clear; do not suddenly switch the question or object in the transition
• if it includes Story Breaks, each break points to an existing chapter and adds no new data conclusions or evidence tasks
• Story Meta.presentation_mode, Story Visual Identity, and Asset Registry are complete; every registry asset has media_hint / purpose / visual_brief / fallback
• every registry asset is used by at least one chapter's SectionVisual.assets ; chapter usage relationships are written as placement / asset / usage
• visual_artifact serves only as SectionVisual.assets[].placement, and is not written as a Pattern, chapter/section type, or complete page plan

Phase 4: Build

Load the corresponding Build document according to the target output, and generate the specific output based on the same plan.md . The Build module reads plan.mdat build time; the final compose/runtime boundary consumes the generated runtime files specified by each Build document and the body HTML / page configuration written by the Agent.

Output	Loaded file	Purpose
HTML	build-html/BUILD.md	Generate an interactive HTML output
PPT	build-ppt/BUILD.md	Generate a presentation-style output

Phase 4's specific build rules, runtime assets, output validation, and format constraints are all defined in their respective Build documents;SKILL.md does not repeat them.

When Build includes charts, the current Agent reads vseed-generation.mdas needed, generates the VSeed configuration based on the Plan, and then assembles it via a local script.

Core principles

1. Each chapter carries only one cognitive task
2. Methods, sources, definitions, and gaps must all be explicitly stated
3. Do not fabricate data, sources, or interviewees
4. Every story must have a Resolution + Ending — this is the core difference from a Dashboard

---

Common failure modes

Failure mode	Symptom	Fix
Data dump	Many charts but no main thread	Pick 1 core insight and organize around it
No Build	After reading SKILL.md, write the HTML / Web-PPT directly by hand	Load the corresponding BUILD.md and generate the final artifact following the build workflow
Pattern selection is arbitrary	Use chart-narrative for all chapters, or use hero-impact by default for all hooks	Choose based on the entry anchor; use hero-impact for openings with a main number or strong background image, cover-intro for openings centered on problem awareness / stakes / why-now; use scrollytelling only for step-by-step breakdowns of a main visual
Scrollytelling step-chart disconnect	The step copy does not correspond to the chart state of the current step, or the chart state barely changes between adjacent steps	Each step must correspond to a clear chart state change; the step narrative should only explain the evidence visible on the chart at the current step. If adjacent steps have no perceptible chart change, merge the steps; for specific writing guidance, follow pattern-scrollytelling-plan.md

---

Data layer design

Data is kept in the persistent Python environment throughout the entire session:

Phase 2: 分析数据 → DataFrame 变量（df_quarterly_returns 等）
Phase 3: 计算 Key Numbers → 精确数值 → 写入 plan.md
Phase 4: Build 时 → 基于 plan.md 中的引用、Key Numbers 和 Style Preset 上下文进行构建

plan.md only stores: variable name references + exact Key Numbers values + Style Preset name. Do not re-embed raw data.

Data consistency guarantee: Every specific number in the narrative text ("up 46%", "82% share") must come from the Key Numbers in plan.md, and Key Numbers must be computed exactly from the DataFrame. Never write numbers based on feeling.

If a chart requires sorting, filtering, reordering, grouping, time windows, or step state changes, prepare the corresponding dataRefin advance. Do not expect the renderer to automatically infer sorting or data transformations.

---

Chart abstraction layer

Charts is an optional evidence-visual field, not a decorative asset contract. Currently only regular statistical charts are supported,renderer is fixed to standard-chart, and must bind dataRefand serve chapter Claim。

Statistical evidence such as trends, comparisons, distributions, compositions, and metric readings must be written into Charts. Do not use visual_artifact、primary_image or evidence_image as a substitute for statistical charts.

Before writing any Charts , first read chart-contract.md. The field contract, regular statistical charts, scrollytelling chart progression, and multi-chart rules all follow that file.

---

Supporting Files

Shared reference files (format-agnostic)

File	Purpose	When to read
references/story-arc-patterns.md	5 arc patterns + chapter roles + transitions	Phase 3a
references/STYLE_PRESETS.md	Visual style selection and asset tone guide	Phase 3d
references/chart-contract.md	Charts fields, regular statistical chart contract, chart progression and multi-chart rules	Before writing any Charts Before
references/vseed-generation.md	The current Agent generates the VSeed configuration and assembles it locally	When Build includes Charts When
references/page-composition.md	Contract for fixed-assembly body text, configuration, and asset references	Before final HTML / PPT assembly
references/image-generation.md	Conventions for host Agent image generation, writing to disk, and missing-asset handling	When Build includes generated image assets

Build module

File	Purpose	When to read
build-html/BUILD.md	Main HTML build instructions (Pattern implementation, component rules, quality checks)	Phase 4（HTML）
build-html/patterns/*.md	HTML implementation of the 8 Section Patterns (templates + structural constraints)	Phase 4 (HTML) reads chapter-based Patterns on demand
build-html/html-templates.md	Shared component HTML fragments	Phase 4（HTML）
build-ppt/BUILD.md	Web-PPT build main instructions (slide mapping, transition pages, capacity rules, quality checks)	Phase 4（PPT）
build-ppt/slide-recipes.md	Translation rules from plan pattern / Story Breaks to slide sequence	Phase 4 (PPT) before building each chapter
build-ppt/layout-recipes.md	Valid data-layout and full-page structure selection	Phase 4 (PPT) before selecting each page's layout
build-ppt/slide-markup.md	PPT slide shell, slots, and fixed markup	Phase 4 (PPT) before filling each slide
build-ppt/asset-handling.md	Valid roles and missing-asset strategies for SVG / image / user assets	Phase 4 (PPT) before placing assets

Shared utility scripts

Only lists workflow entry points shared by HTML / PPT and callable by Build; build-specific scripts are described only in the corresponding BUILD.md .

File	Purpose
scripts/validate_story_plan.py	Validate plan structure before Build
scripts/assemble_story_specs.py	Locally assemble the Agent-generated config and Plan / data into spec_map.json
scripts/normalize_story_assets.py	Generate resolved_asset_bindings.json
scripts/compose_story.py	Fixed assembly of HTML / PPT, binding normalized assets
scripts/validate_js.py	Validate final HTML / Web-PPT output