# Data Brief

> 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".

- Skill: `carrielabs/data-brief` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add carrielabs/data-brief`
- Raw SKILL.md: https://api.skillmd.com/api/skills/carrielabs/data-brief/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: carrielabs (https://skillmd.com/u/carrielabs)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/carrielabs/data-brief

---


# 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*
*主文件。只做流程调度，不包含规则细节。*