| name | RA:metadata-refine |
| description | Use when analysis jobs, user feedback, profile outputs, or real-data probes need to be converted into reference materials for later RA:metadata maintenance; trigger for metadata 修正材料, 字段定义不清, 指标口径待修, evidence 补充, job feedback, profile-based metadata refinement. |
Metadata Refine Skill
RA:metadata-refine 只生成元数据修正参考材料。它读取分析 job、用户反馈、profile 和必要的数据探查结果，把问题整理成可审查文件；正式 YAML 仍由 RA:metadata 维护。
执行前复用 RA:getting-started doctor 的项目环境摘要；本 skill 可以读取 job / CSV / profile 做参考包，但不自行寻找其它 Python、DuckDB CLI 或 registry 写入路径。
When to Use
使用本 skill：
- 用户反馈字段定义、指标口径、证据来源或 review 标记有问题。
- 分析 job 中记录了 metadata 相关问题，需要整理成修正材料。
- 需要基于真实 CSV / profile 补充字段观察、样例值、枚举候选、空值率或类型信号。
- 需要把临时 refine 材料归档到
metadata/sources/refine/，供 RA:metadata 引用。
- 需要把分析阶段发现的 metadata 问题整理成后续
RA:metadata 的输入。
不要使用本 skill：
- 直接修改
metadata/datasets/*.yaml、metadata/mappings/*.yaml 或 metadata/dictionaries/*.yaml。使用 RA:metadata。
- 执行正式分析、写报告或生成业务结论。使用
RA:analysis-run / RA:report。
- 发布 index 或同步
runtime/registry.db。使用 RA:metadata validate/index/sync-registry。
- 把 profile、sample values、enum candidates、nullable、physical type 或 source mapping 写回 dataset YAML。
Workflow
- 记录或读取分析反馈：
python3 {baseDir}/skills/metadata-refine/scripts/collect_feedback.py --session-id <SESSION_ID> --list
python3 {baseDir}/skills/metadata-refine/scripts/collect_feedback.py --session-id <SESSION_ID> --issue-type field_definition_unclear --summary "字段含义需要确认"
- 如需看真实数据，基于 job 内正式 CSV 做轻量探查：
python3 {baseDir}/skills/metadata-refine/scripts/probe_data.py --session-id <SESSION_ID> --data-csv jobs/<SESSION_ID>/data/<file>.csv --dataset-id <dataset_id>
metadata-only 场景没有 analysis job 时，也可以直接传 dataset 和 CSV：
python3 {baseDir}/skills/metadata-refine/scripts/probe_data.py --dataset-id <dataset_id> --data-csv <file>.csv
- 生成参考材料包：
python3 {baseDir}/skills/metadata-refine/scripts/build_reference_pack.py --session-id <SESSION_ID> --dataset-id <dataset_id>
python3 {baseDir}/skills/metadata-refine/scripts/build_reference_pack.py --dataset-id <dataset_id> --data-csv <file>.csv --profile-json <profile.json>
如果目标是从 RA:metadata-report 的未维护项出发做 guided workflow，可以使用一条命令生成真实数据探查证据和候选维护建议：
python3 {baseDir}/skills/metadata-refine/scripts/resolve_report_gaps.py --dataset-id <dataset_id> --data-csv <file>.csv
该脚本会读取正式 CSV，探查字段 cardinality、日期范围、数值范围、likely grain 和 candidate key fields，生成 runtime/metadata-refine/{refine_id}/ 参考包。加 --run-loop 时会继续驱动 metadata validate、metadata index、metadata sync-registry --dry-run 和 RA:metadata-report；它只验证维护链路，不自动改正式 YAML。
默认输出到：
runtime/metadata-refine/{refine_id}/
refine_brief.md
refine_followup.md
feedback_summary.md
data_probe_summary.md
metadata_update_reference.md
evidence_manifest.json
- 完成后归档，不在 runtime 长期保留：
python3 {baseDir}/skills/metadata-refine/scripts/archive_reference_pack.py --refine-id <refine_id> --session-id <SESSION_ID>
归档后位置：
metadata/sources/refine/{refine_id}/
- 交给
RA:metadata 继续维护 YAML：
/skill RA:metadata
基于 metadata/sources/refine/{refine_id}/ 的参考材料修正对应 metadata YAML，并运行 validate/index/sync-registry。
Boundaries
runtime/metadata-refine/ 是临时工作区。metadata/sources/refine/ 是归档证据区。evidence_manifest.json 必须记录 job_id、输入 CSV、profile、feedback 和归档路径；正式 YAML 只能通过 business_definition.ref 引用关联记录，不复制 evidence。- 参考材料可以提出建议，但不得声明为已确认口径。
- CSV/header/display name 问题只记录为 export/display 反馈；不得建议把 dataset
fields[].name 改成中文展示名。
- profile 输出只允许留在
runtime/metadata-refine/ 草稿区或归档后的 metadata/sources/refine/；不得自动生成 dataset YAML patch。
- 枚举候选、样本值、空值率和物理类型只能作为 registry upsert / data_probe 建议，不得写成
enum_values、sample_profile、sample_values、top_values、duckdb_type 或 nullable 字段。
- 发现 source 字段映射时，只生成
metadata/mappings/*.yaml 维护建议，不在 dataset fields/metrics 内嵌 source_mapping。
- 如果材料含样例值或业务敏感信息，归档前必须先脱敏或确认该项目允许保存。
Completion Summary
完成后用下面结构向用户汇报，并按本次结果动态裁剪：
完成情况：
- 已读取来源：<job、profile、CSV、feedback、用户反馈>
- 已生成 refine pack：`metadata/sources/refine/{refine_id}/`
- 已生成参考文件：<evidence_manifest.json、metadata_update_reference.md、refine_followup.md>
下一步建议：
- 最推荐下一步：/skill RA:metadata ...（基于 refine pack 修正正式 YAML）
- 可选下一步：/skill RA:metadata-report ...（修正后生成长期口径说明）
- 可选下一步：/skill RA:analysis-run ...（下一次分析复用更好的 metadata）
边界提醒：
- 本 skill 只整理和归档参考材料，没有直接修改正式 YAML。
- 正式写回必须由用户主动进入 /skill RA:metadata，并运行 validate / index / sync-registry。
