data-brief

name	data-brief
description	Use this skill when the user provides a dataset (CSV, Excel, JSON, SQL dump, or raw text data) and asks for analysis, insights, a data report, a dashboard, or any form of data visualization. Trigger phrases include: "analyze this data", "make a dashboard", "what does the data say", "give me insights", "build a report", "data brief", "data-brief", "data visualization", "帮我分析数据", "做一个数据看板", "给我洞察", "数据简报", "做个报告". Also triggers when user shares a file path to a data file and asks "what can you find" or "tell me what this data says".
version	1.0.0

data-brief

数据决策简报生成 Skill

---

永久约束 — ALWAYS IN EFFECT

以下规则在所有阶段永久生效，不依赖任何支撑文件的加载顺序，不因 Phase 而改变。

① 图表标题必须是结论句，不是描述词
   ❌ "各渠道月度用户增长趋势"
   ✅ "搜索渠道增速是社交渠道的 3.2 倍"

② 所有 ECharts 图表的 data 数组，必须 100% 来自 data_lock.json
   禁止在生成 HTML 时重新计算、四舍五入、或"约等于"任何数字

③ 输出必须是单体 HTML 文件（Self-contained）
   外部依赖仅限：Google Fonts CDN + ECharts CDN
   禁止引用任何本地文件或其他框架

④ N < 30 的数据分组不参与主要分析
   可出现在报告附录，标注"样本不足，数据仅供参考"

⑤ 最终洞察集必须包含至少 1 条负面预警或效率陷阱
   全部正面 = 报告不合格，退回 Phase 3 重新扫描

---

这个 Skill 做什么

用户给你数据，你输出一份可以直接发给老板或客户的 HTML 数据报告。

报告要达到的标准：

• 每一条洞察，聪明人看了会停顿，不会点头说"嗯，知道了"
• 每一个数字，都有对比对象，不是孤立存在
• 每一个建议，明天就能执行，不是模糊的"应该关注"
• 整份报告，可以双击 HTML 文件在浏览器里完整运行

这个 Skill 的核心设计原则：给 AI 戴最严密的工程镣铐，逼出最高质量的产出。

---

架构说明（Progressive Disclosure）

本 Skill 的主文件（SKILL.md）只做流程调度。 规则内容分散在支撑文件里，按需加载，不提前读取。

文件加载时序（严格遵守）：

Phase 1-2：不加载任何支撑文件
Phase 3：  READ ${CLAUDE_SKILL_DIR}/PATTERN_HUNT.md
Phase 4：  READ ${CLAUDE_SKILL_DIR}/INSIGHT_RULES.md + READ ${CLAUDE_SKILL_DIR}/ANTI_AI.md
Phase 5：  READ ${CLAUDE_SKILL_DIR}/REPORT_TEMPLATES.md
Phase 7：  READ ${CLAUDE_SKILL_DIR}/THEMES.md + READ ${CLAUDE_SKILL_DIR}/CHART_LIBRARY.md

不允许在 Phase 1-2 加载视觉文件（会污染分析注意力）
不允许在 Phase 3 前加载 INSIGHT_RULES.md（先找模式，再评判）

---

9 个执行阶段

---

Phase 1 · 接收输入与目标校准

做什么： 理解数据是什么，报告给谁看，要回答什么问题。

执行步骤：

1. 接收数据（文件路径 / 粘贴内容 / 描述）
   → 确认数据格式（CSV / Excel / JSON / 文字描述）
   → 确认数据规模（行数、列数、时间跨度）

2. 询问（如果用户没有主动说）：
   - "这份报告主要给谁看？" [选项：技术团队 / 业务负责人 / 高管/投资人]
   - "最希望这份报告回答什么问题？" [用户自由描述]
   - "有没有特别想聚焦的核心指标？
     比如：均值 / 总量 / 转化率 / 增长率 / 某个具体字段名
     可以直接说，也可以选「无，你来判断」"
     → 如果用户指定了指标，Phase 2 和 Phase 3 必须以该指标为主轴展开分析
     → 如果用户说「无」或跳过，由 Claude 根据数据分布自主选择最有区分度的指标，
       并在 Phase 2 结束后告知用户："我选择以 [X] 作为核心分析指标，原因是 [Y]"

   如果用户说"你自己决定"→ 根据数据内容推断受众，记录推断理由

3. 根据受众，确定报告参数：
   受众=技术团队  → 主题:Deep Analyst, 洞察上限:7条, 布局:全局分析
   受众=业务负责人 → 主题:Paper & Ink,  洞察上限:5条, 布局:全局分析
   受众=高管/投资人 → 主题:Swiss Signal, 洞察上限:3条, 布局:单一决策

输出： 一句话摘要，告知用户你将做什么（不等待用户确认，直接进入 Phase 1.5）

---

Phase 1.5 · 业务上下文注入

做什么： 收集数据之外的信息，防止把已知事件当作"反直觉发现"。

执行步骤：

向用户问一个问题（只问这一个，不展开追问）：

"这段数据期间，有什么数据本身看不出来的背景信息吗？
 比如：做了大促 / 上线了新功能 / 竞品出了问题 / 砍掉了某个渠道"

如果用户说有 → 记录业务事件及时间，在 Phase 3 扫描时标注为"排除项"
如果用户说没有 / 跳过 → 继续，Phase 3 中所有异常都视为真实待解释的现象

注意： 如果数据时间范围只有1个月或数据极少，跳过本步骤。

---

Phase 2 · 数据剖析

做什么： 运行 Python 脚本，生成结构化的数据摘要 JSON，交给后续阶段用。

⚠️ 不加载任何支撑文件（保持分析注意力集中）

执行步骤：

如果有可运行的 Python 环境：
  → 运行 ${CLAUDE_SKILL_DIR}/scripts/profile_data.py，输入数据文件路径
  → 输出 data_summary.json 和 data_lock.json（见脚本说明）

如果没有 Python 环境（用户粘贴了原始数据）：
  → 手动计算以下统计量：
    · 每列的：数据类型 / 非空值数量 / 唯一值数量
    · 数值列的：均值 / 中位数 / 标准差 / min / max
    · 分类列的：top 5 频率分布
    · 时间列（如有）：起止时间 / 月度或周度趋势
    · 关键指标的分组聚合（按主维度分组）

样本量硬性过滤（NON-NEGOTIABLE）：

所有分组分析：N < 30 的分组，不参与主要分析。
              这些分组记录到 excluded_groups.json，
              在报告附录中注明"样本不足，数据仅供参考"。

绕过此规则（例如手写 N=4 的结论）= 违规，直接删除。

生成 data_lock.json（关键）：

将用于图表的所有数据系列，以 JSON 格式锁定：
{
  "chart_id": {
    "series_name": [数值数组],
    "categories": [类别数组],
    "meta": {"N": 数字, "unit": "单位", "source_col": "列名"}
  }
}

Phase 7 生成 ECharts 时，data 数组必须 100% 来自此文件，
禁止任何四舍五入、重算或"约等于"处理。

---

Phase 3 · 反直觉模式扫描

做什么： 系统性扫描 7 类反直觉模式，找到候选洞察。

开始时读取： PATTERN_HUNT.md

执行步骤：

1. 按 PATTERN_HUNT.md 的 7 个方向逐一扫描
   对每个方向：找到的记录，没有的写"未发现"

2. 对照 Phase 1.5 的业务上下文，标记"排除项"
   （已知事件导致的异常，不作为洞察）

3. 汇总候选洞察，去重合并
   目标：5-15 条候选洞察（多多益善，Phase 4 会筛选）

4. 输出 3 个"故事方向"摘要（内部决策，不展示给用户）：
   方向A：[最反直觉的单一发现]
   方向B：[最有行动价值的发现组合]
   方向C：[最能回答用户在 Phase 1 提出的问题的发现]

   → 自动选择最能回答用户原始问题的故事方向
   → 在报告页脚注明："本报告聚焦 [方向]，另发现 [N] 个次级信号未展开"

---

Phase 4 · 洞察起草与质检

做什么： 把候选洞察写成正式文字，通过 6 项测试，形成最终洞察集。

开始时读取： INSIGHT_RULES.md + ANTI_AI.md

执行步骤：

对每条候选洞察：

Step 4a：写草稿
  → 按 Fact/Hypothesis 双层结构起草
  → Fact 层：≤60字，≤4标点，只写数据事实，无原因
  → Hypothesis 层：明确标注"AI推测"，附验证建议

Step 4b：6项测试（INSIGHT_RULES.md）
  □ 测试1：反常识检验
  □ 测试2：行动测试
  □ 测试3：机制测试（相关性 ≠ 因果性）
  □ 测试4：惊讶测试
  □ 测试5：颗粒度测试
  □ 测试6：Pointer Test（必须找到数据指针）

  未通过任何一项 → 删除整条，不讨论，不妥协

Step 4c：ANTI_AI 检查（ANTI_AI.md）
  → 禁止词检查
  → 句式检查（无因果断言/万金油建议/孤立数字）
  → 长度检查（≤60字/≤140字）

Step 4d：强制负面配额
  → 检查洞察集里是否有至少1条负面预警或效率陷阱
  → 没有 → 重回 Phase 3 重新扫描

Step 4e：数量控制
  → 按受众上限裁减（3 / 5 / 7条）
  → 优先保留行动价值最高的

---

Phase 5 · 报告结构设计

做什么： 决定报告的布局、Chapter 顺序、图表类型。

开始时读取： REPORT_TEMPLATES.md

执行步骤：

1. 根据受众选择布局方案（A: 全局分析 / B: 单一决策 / C: 对比分析）

2. 为每条洞察指定：
   - 归属 Section（章节号 + 主题词）
   - 对应图表类型（从 CHART_LIBRARY.md 选，Phase 7 时加载）
   - 在信息金字塔中的层级（第一层/第二层/第三层）

3. 确定北极星数字（整份报告最重要的单一指标）

4. 规划执行摘要卡片组（2-4 张，对应受众最关心的问题）

---

Phase 6 · 数据验证（防幻觉检查）

做什么： 在生成 HTML 之前，最后一次校验数字的准确性。

⚠️ 关键阶段，不跳过

执行步骤：

1. 对照 data_lock.json，逐一核对洞察文字里的每个数字
   → 每个数字必须能在 data_lock.json 里找到对应来源
   → 数字不匹配 → 用 data_lock.json 里的数字覆盖洞察文字

2. 检查 Pointer Test 指针的完整性
   → 每条洞察必须有数据指针（行范围 / 原文引用）
   → 找不到指针的洞察，在此阶段删除

3. 最终洞察集冻结
   → 数字和文字确认无误后，不再修改
   → 进入 Phase 7 的 HTML 生成，只是把已确认的内容写成代码

---

Phase 7 · HTML 生成

做什么： 把已确认的数据和洞察，按模板写成完整的单体 HTML 文件。

开始时读取： THEMES.md + CHART_LIBRARY.md

执行步骤：

1. 从 THEMES.md 加载当前主题的 CSS 变量和 ECharts 主题配置

2. 写 HTML 骨架（参考 REPORT_TEMPLATES.md 的对应布局方案）

3. 写 CSS（完整内联，不引用外部样式文件）

4. 写 ECharts 图表（参考 CHART_LIBRARY.md 的配置片段）
   NON-NEGOTIABLE：所有 data 数组 100% 来自 data_lock.json
   禁止任何形式的数字重新计算或四舍五入

5. 写洞察卡片（参考 REPORT_TEMPLATES.md 组件 E）
   Fact/Hypothesis 双层结构，数据指针作为悬停 (i) 图标

6. 写页脚（主题名 + 数据来源 + 样本量）

7. 写 ECharts 初始化代码
   必须使用主题名初始化：echarts.init(el, '[theme-name]')
   不允许不带主题名的裸初始化

NON-NEGOTIABLE 检查清单（生成完毕后，逐项过）：

□ 图表标题是结论句（不是描述词）
□ 所有 ECharts series 包含 shadowBlur: 0
□ Tooltip 按主题规格重写（不是 ECharts 默认样式）
□ 卡片无 box-shadow（除 Theme 1 允许的极小阴影外）
□ 图表数据区无渐变（纯色填充）
□ 每个图表下方有洞察卡片（无裸图）
□ HTML 是单体文件（无本地 JS/CSS 引用，仅 CDN）
□ 页脚存在且包含主题名和数据来源

---

Phase 8 · 内部审查（Red Teaming）

做什么： 在输出给用户之前，对每条洞察进行内部反驳检验。用户不可见。

执行步骤：

对每条洞察，扮演"挑刺者"：
"同一份数据里，有没有其他维度可以推翻这个结论？"

找到反例数据：
  → 洞察本身是错的 → 删除，不输出
  → 在某子群体成立，在另一个不成立 → 加限定条件，修改 FACT 层
  → 两个维度互相矛盾 → 整条降级为 HYPOTHESIS，标注"待确认"

找不到反例 → 洞察通过 Red Teaming，保留

检查"正面偏差"：
  → 最终洞察集是否清一色都是好消息？
  → 是 → 强制重审，至少找到1条负面预警或效率陷阱加回来

---

Phase 9 · 交付

做什么： 输出最终文件，告知用户关键发现。

执行步骤：

1. 输出 HTML 文件（单体，完整可运行）

2. 在 Chat 里简要告知（不要重复 HTML 里已有的内容）：
   - 数据规模（N=X条，时间范围）
   - 最关键的 1 条洞察（一句话）
   - 报告使用的视觉主题
   - 如有被排除的低样本分组，告知数量

3. 如有被 Red Teaming 删除或降级的洞察，告知用户数量
   （不告知具体内容，只说"有X条发现因为可被反驳而未收入报告"）

---

全局 NON-NEGOTIABLE 规则

以下规则适用于所有阶段，任何阶段违反均为错误。

数据完整性：
□ 所有图表数据来自 data_lock.json，不允许重算
□ N<30 的分组不参与主要分析（只出现在附录）
□ 每条洞察有数据指针（找不到 = 删除）

写作质量：
□ 禁止 ANTI_AI.md 中的所有禁止词和禁用句式
□ 图表标题必须是结论句，不是描述词
□ Fact 层和 Hypothesis 层必须分离，不允许混写

文件输出：
□ HTML 是单体文件（Self-contained）
□ 外部依赖仅限 Google Fonts CDN 和 ECharts CDN
□ 所有图表使用主题名初始化（不裸初始化）

质量底线：
□ 最终洞察集包含至少 1 条负面预警
□ 每条洞察通过全部 6 项测试
□ 报告包含页脚（主题名 + 数据来源 + 时间范围）

---

文件加载速查

Phase	加载的文件	原因
1	无	只做问答
1.5	无	只做问答
2	无	运行 Python 或手动统计，专注数字
3	PATTERN_HUNT.md	反直觉模式扫描清单
4	INSIGHT_RULES.md + ANTI_AI.md	洞察质检 + 去AI化
5	REPORT_TEMPLATES.md	报告结构和 HTML 组件
6	无	只做数字核对
7	THEMES.md + CHART_LIBRARY.md	视觉生成
8	无	内部审查，不需要额外文件
9	无	只做输出

---

SKILL.md — data-story skill v1.0 主文件。只做流程调度，不包含规则细节。