mcpField
M
metric-reconciliation

metric-reconciliation

github.com/nimrodfisherData & databases504263 installsUpdated 5w ago
Repository

About metric-reconciliation

metric-reconciliation is a data-analysis skill for tracing differences between reported metrics. It guides analysts through definition checks, source comparisons, root-cause analysis, and documented resolution.

Key features

  1. 01Clarify metric definitions and scope
  2. 02Compare values across two sources
  3. 03Calculate gaps and tolerances
  4. 04Trace queries and pipeline steps
  5. 05Document causes and resolutions

Use cases

  1. 01Resolve conflicting dashboard KPIs
  2. 02Investigate metric changes after pipeline updates
  3. 03Validate a new data model against a legacy source
  4. 04Explain a disputed business metric

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/nimrodfisher/data-analytics-skills --skill metric-reconciliation

After installing, type/metric-reconciliationin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

assets/
reconciliation_report_template.md
references/
reconciliation_patterns.md
scripts/
reconcile_metrics.py

Details

From the project README

Metric Reconciliation

When to use

  • Two dashboards or reports show different values for the same KPI
  • A metric changed unexpectedly after a data pipeline update
  • Stakeholders question a number and need an authoritative explanation
  • Preparing to merge or deprecate a legacy reporting source
  • Onboarding analysts to a new data model and validating it against the old one

Process

  1. Define the metric and scope — confirm the exact definition (numerator, denominator, filters, time zone) and the period under investigation. Mismatched definitions are the most common cause of discrepancy.
  2. Pull values from both sources — extract the metric values for the same period from each source. Record absolute values, row counts, and the query or calculation path used.
  3. Compute the gap — calculate the absolute difference and percentage gap. If the gap is within an agreed tolerance (e.g., ±0.1%), document it as accepted and close. See references/reconciliation_patterns.md for tolerance guidelines.
  4. Trace the computation path — walk each source's query or pipeline step by step. Common divergence points: different join types, filter order, null handling, date truncation, or deduplication logic.
  5. Identify the root cause — classify the cause using references/metric_discrepancy_guide.md (definition mismatch, data freshness, aggregation grain, calculation bug). Document the divergence point with a code snippet or query excerpt.
  6. Resolve and document — fix the calculation or accept a canonical source, then complete assets/reconciliation_report_template.md and share with stakeholders.

Inputs the skill needs

  • The metric name and business definition (numerator, denominator, any known variants)
  • Access to both sources (queries, dashboard SQL, or raw data)
  • The time period showing the discrepancy
  • Row counts or record-level data to enable line-by-line comparison if needed
  • Any known recent changes to pipelines, schema, or business rules

Output

  • assets/reconciliation_report_template.md — completed report showing source A vs. source B, the gap, root cause, and resolution status
  • A corrected query or pipeline change (if a bug was found)
  • A documented tolerance agreement (if the gap is acceptable)

Comments

Markdown supported