| name | RA:getting-started |
| description | Use when a user first installs RealAnalyst, asks how to start, wants to extract metadata from Tableau/DuckDB/files, or wants to know what information to prepare before registering datasets or running analysis. |
Getting Started
RealAnalyst 从抽取和确认 metadata 开始，不从 SQL 或报告开始。
本 skill 是 lightweight guide + skill router + minimal status check。它只识别用户目标、检查当前项目是否已有 metadata / registry / dataset，并输出一条可复制的下一步 /skill 指令。
执行前先固定项目环境，不让 agent 自己到处猜：
python3 {baseDir}/skills/getting-started/scripts/doctor.py --intent start
doctor 是只读检查，只输出 JSON：Python 命令、skill base、shared lib、registry path、DuckDB path、依赖状态、metadata / registry / export readiness 和推荐下一 skill。它不创建目录、不安装依赖、不取数、不写 metadata、不写 runtime/registry.db。
禁止在本 skill 中：
- 创建正式 analysis job。
- 执行取数。
- 生成业务报告。
- 自动注册正式 metadata。
- 自动进入正式分析。
First Step
第一步是问清楚用户要做什么，不要先创建目录：
- Tableau workbook / view / dashboard
- DuckDB database / table / view
- CSV / Excel / 其他文件
- 已有 metadata / registry，想进入正式分析
- 已有报告，想做交付前验证
- 已有 job feedback，想归档口径问题
- 暂时没有数据源，只想先整理字段和指标口径
做最小状态检查：
- 先运行
skills/getting-started/scripts/doctor.py，以输出中的 python_command、skill_base_dir、registry_path 为本轮固定环境。
- 是否存在
metadata/datasets/。
- 是否存在
runtime/registry.db。
- 用户是否已经给出 dataset id、source id、Tableau workbook/view、DuckDB path/table、CSV/Excel path/sheet 或业务文档。
- 是否已有本次分析需要的字段、指标和筛选条件。
如果 doctor 报告 scripts_py_exists=false、scripts_py_probe_failed、missing_shared_lib、关键依赖缺失或 registry path 不一致，先让用户按本项目初始化命令修环境；不要切到自由 which/find/python3 -c/import duckdb 探测，也不要用 DuckDB CLI 或 sqlite3 绕过受控入口。
然后告诉用户需要准备哪些信息：
| Need | Examples |
|---|
| Source | Tableau workbook/view/dashboard，DuckDB path/table，CSV/Excel path/sheet |
| Fields | 字段名、字段类型、业务含义、是否需要脱敏 |
| Metrics | 指标公式、单位、粒度、业务含义 |
| Filters | Tableau filter/parameter，SQL where 条件，时间范围 |
| Evidence | 来源文档、dashboard 备注、SQL、owner 确认记录 |
| Open questions | 缺失定义、不确定筛选器、是否需要业务 review |
Choose One Path
- Tableau：先确认
.env 是否已填写 Tableau 连接信息，再确认 workbook/view/dashboard 名称，然后做 discovery，抽取字段、筛选器和参数。
- DuckDB / 文件数据：先确认路径、表名或 sheet 名，再抽取字段和样例口径。
- 手工整理：先让用户提供字段、指标和业务口径，不创建目录。
- 已有 metadata / registry：推荐进入
RA:analysis-run 做正式分析。
- 只想看长期口径说明：推荐进入
RA:metadata-report。
- 分析后发现口径问题：推荐进入
RA:metadata-refine。
- 检查已有报告：推荐进入
RA:report-verify。
只有用户明确同意“保存到项目”时，才创建 metadata/ 并按新分层写入 metadata/sources/、metadata/dictionaries/、metadata/mappings/、metadata/datasets/<dataset_id>.yaml。不要在 getting-started 阶段主动运行 metadata.py init。
当用户想分析但数据未注册时，推荐先走 RA:metadata 做最小可分析注册，而不是直接推荐 RA:analysis-run。
Teach Skills
用户问“怎么用”时，给这些快捷入口：
/skill RA:metadata
帮我整理这个数据源的字段、指标、筛选器和业务口径。先问我要哪些材料，不要直接创建文件。
/skill RA:metadata
帮我整理这些指标：名称、公式、单位、粒度、业务含义、来源证据和待确认问题。
/skill RA:metadata
帮我整理术语表：中文名、英文名、同义词、定义、来源证据和 review 状态。
/skill RA:metadata-report
帮我查看这个数据集的长期口径说明，列出字段、指标、筛选入口、使用边界和待补齐项。
/skill RA:analysis-run
基于已确认 metadata 和 registry，帮我执行正式完整分析。先生成计划并等我确认，再执行取数、画像、分析、报告和验证。
/skill RA:report-verify
帮我验证这份报告是否可交付，重点检查数据来源、口径状态、结论证据和待复核项。
Handoff
环境检查入口：
python3 {baseDir}/skills/getting-started/scripts/doctor.py --intent analyze
python3 {baseDir}/skills/getting-started/scripts/doctor.py --intent metadata
元数据抽取并落盘后，再进入 metadata 校验和检索：
python3 {baseDir}/skills/metadata/scripts/metadata.py validate
python3 {baseDir}/skills/metadata/scripts/metadata.py index
python3 {baseDir}/skills/metadata/scripts/metadata.py search --type all --query <keyword>
python3 {baseDir}/skills/metadata/scripts/metadata.py context --dataset-id <dataset_id>
之后再进入 RA:analysis-run。RA:analysis-plan、RA:data-export、RA:data-profile、RA:report 通常由 RA:analysis-run 编排。
Completion Summary
本 skill 完成时，用下面结构向用户汇报，并按本次结果动态裁剪：
完成情况：
- 已识别用户目标：<从哪里开始 / 注册 metadata / 正式分析 / 口径说明 / refine / verify>
- 已完成最小状态检查：metadata=<有/无>，registry=<有/无>，dataset=<已知/未知>
- 已整理待准备信息：<字段、指标、筛选器、证据、待确认项>
下一步建议：
- 最推荐下一步：/skill RA:metadata ...（数据未注册或字段/指标/口径不足）
- 可选下一步：/skill RA:analysis-run ...（metadata 和 registry 已准备好）
- 可选下一步：/skill RA:metadata-report ... / /skill RA:metadata-refine ... / /skill RA:report-verify ...（仅在用户目标匹配时保留）
边界提醒：
- 本 skill 没有创建正式 analysis job、没有取数、没有生成业务报告，也没有自动注册正式 metadata。
