metric-reconciliation

メトリクスの不一致調査

使用する場面

• 2つのダッシュボードまたはレポートで、同じKPIの値が異なる
• データパイプラインの更新後に、メトリクスが予期せず変化した
• 関係者から数値について疑問が出ており、信頼できる説明が必要
• 古いレポートソースの統合または廃止を準備している
• アナリストに新しいデータモデルを導入し、古いモデルと照合して検証する

プロセス

1. メトリクスと対象範囲を定義する — 正確な定義（分子、分母、フィルター、タイムゾーン）と調査対象期間を確認します。定義の不一致が、差異の最も一般的な原因です。
2. 両方のソースから値を取得する — 各ソースから同じ期間のメトリクス値を抽出します。絶対値、行数、使用したクエリまたは計算手順を記録します。
3. 差を計算する — 絶対差と差の割合を計算します。差が合意済みの許容範囲内（例：±0.1%）であれば、許容済みとして記録し、調査を終了します。許容範囲のガイドラインについては、references/reconciliation_patterns.md を参照してください。
4. 計算手順をたどる — 各ソースのクエリまたはパイプラインを、ステップごとに確認します。よくある差異の発生箇所：異なる結合タイプ、フィルターの適用順序、NULL の処理、日付の切り捨て、または重複排除のロジック。
5. 根本原因を特定する — references/metric_discrepancy_guide.md を使って、原因を分類します（定義の不一致、データの鮮度、集計粒度、計算のバグ）。コードスニペットまたはクエリの抜粋を使って、差異の発生箇所を記録します。
6. 解決して記録する — 計算を修正するか、正式なソースを採用したうえで、assets/reconciliation_report_template.md に記入し、関係者と共有します。

スキルに必要な入力

• メトリクス名とビジネス上の定義（分子、分母、既知のバリエーション）
• 両方のソースへのアクセス（クエリ、ダッシュボードのSQL、または生データ）
• 差異が見られる期間
• 必要に応じて1行ずつ比較できる行数またはレコード単位のデータ
• パイプライン、スキーマ、またはビジネスルールに関する最近の変更（判明している場合）

出力

• assets/reconciliation_report_template.md — ソースAとソースBの比較、差、根本原因、解決状況を示す完成済みレポート
• 修正済みのクエリまたはパイプラインの変更（バグが見つかった場合）
• 許容範囲に関する合意の記録（差が許容できる場合）