| 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>
默认输出到:
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。