fleur-dbt-model-readiness

Staging Model Readiness

在写或重写 pipeline/elt/models/staging/** 前使用本 skill。目标是先理解 raw source 的真实数据质量和数据特征，再设计 staging 清洗、字段治理和 tests。

必读入口

1. AGENTS.md 的 dbt 入口。
2. docs/ADR/0007-dbt-staging-cleaning-boundary.md。
3. docs/ADR/0008-raw-source-profiling-before-dbt-staging.md。
4. docs/RFC/archive/0013-raw-source-profiling-before-dbt-staging.md。
5. docs/plans/archive/0025-raw-source-profiling-before-dbt-staging-implementation-plan.md。

Workflow

1. 确认目标 staging model 和直接 raw inputs。
   • 读取 pipeline/elt/models/sources.yml。
   • 读取对应 pipeline/contracts/datasets/<dataset>.yml。
   • 如存在，读取 docs/references/data_dict/<dataset>.md。
2. 按 dbt discovering-data 方法完成 raw profiling。
   • inventory。
   • sample raw data。
   • row count、日期/分区范围。
   • grain 和候选自然键。
   • null、空字符串、占位值。
   • 枚举值和 top values。
   • 证券代码/日期/高价值字符串格式。
   • 数值范围、负数、零值、极端值和单位判断。
3. 写入 docs/references/raw_profile/<dataset>.md。
4. 在 report 前半部分提炼“数据分析发现”，不要只留下 SQL 输出。
   • 数据量、覆盖范围、分区范围。
   • grain、候选键、重复情况；如存在新旧候选键，必须对比说明。
   • 关键字段 null / 空字符串 / 占位值，并解释哪些是预期缺失。
   • 证券代码、日期、报告期、状态字段等高价值字段的格式和异常样本。
   • 枚举分布、长尾文本、低频异常值；必要时补充字段间相关性。
   • 时间字段范围和业务合理性检查，例如日期先后关系。
   • 数值字段负数、零值、极端值和单位判断。
   • 只把已执行查询支持的事实写成结论；推断必须标明为判断。
5. 从 report 中提取 staging 设计：
   • rename。
   • cast。
   • normalize。
   • null handling。
   • data tests。
   • YAML config.meta.source_columns 和 normalization metadata。
   • deferred to intermediate/mart。
6. 只有完成 raw profile 后，再写 staging SQL/YAML。
7. 运行验证。

Report Shape

raw profile report 应采用“结论优先，证据后置”的结构。SQL 附录用于追溯， 但 reviewer 应能先通过“数据分析发现”和“Staging 设计决策”判断模型怎么写。

推荐章节：

1. 范围与执行信息：命令、日期、状态、contract、source、ClickHouse raw 表。
2. 数据分析发现：用分组 bullet 写高信号事实。
   • 数据量与覆盖：总行数、distinct 主体数、分区 / 日期范围。
   • 粒度与候选键：候选键去重结果、旧键对比、重复样本归因。
   • 缺失与占位：关键字段 NULL、空字符串、1970-01-01、供应商占位。
   • 格式与参照完整性：证券代码格式、报告期标签、是否能命中直接依赖 raw input。
   • 分布与相关性：枚举 top values、少量值、长尾文本、字段间强相关。
   • 时间合理性：min/max、日期顺序异常、批次时间范围。
   • 数值合理性：负数、零值、极端值、单位假设。
3. 字段画像：保留逐字段表，用于快速查 NULL、占位、distinct 和备注。
4. 数据质量问题：只列实际发现的问题；通用风险不要写成问题。
5. Staging 设计决策：明确每个清洗动作是否进入 staging、测试和 metadata。
6. 延后到 Intermediate/Mart：跨源归并、业务优先级、主数据修正、复杂文本归一化。
7. 待确认问题。
8. 关键 SQL 证据摘要：只放支撑结论的高信号结果。
9. 验收清单：保持 ## 9. 验收清单 标题，兼容 readiness lint。
10. Profiling SQL 与结果：保留高信号、可复核的查询和输出。