m7mdwb conversion-reconcile
Agent workflow
This is an executable comparison. When two usable exports are available, run the bundled reconciler instead of debating attribution in the abstract.
- Identify which file is the marketing/analytics platform export and which is the CRM or finance source of truth. Inspect filenames and headers first; ask only when the roles are genuinely ambiguous.
- Confirm both files contain row-level conversions and a shared identifier. Aggregated daily totals cannot support the join this skill makes. Read references/input-guide.md when the user needs an export recipe.
- Resolve
scripts/reconcile.pyrelative to thisSKILL.mdand run it with an available Python 3 interpreter. In Claude Code,${CLAUDE_SKILL_DIR}is this skill directory; in other hosts use the skill path supplied by the host. Quote every path. Let key auto-detection run first; pass--key NAMEwhen the shared field has another name. - Interpret exit codes exactly:
0means no material divergence shape was diagnosed,1means one or more evidence-backed diagnoses were produced, and2means the inputs could not support a trustworthy comparison. On2, relay the corrective message and stop. - Report the join quality and ratio before the ranked causes. Lead with the top cause's evidence and next check, but retain credible secondary causes. Never turn a heuristic confidence weight into a calibrated probability.
Do not modify either export, imply that attribution was modelled, or claim the tracking is correct merely because no known divergence shape fired.
When to use this
- "The platform says 400 conversions, the CRM says 260."
- "Sales don't trust the marketing dashboard."
- "Our cost per acquisition looks too good."
- Before presenting any number to a board, an investor or a budget owner.
- After a tracking migration, a consent tool rollout, or a move to server-side tagging.
Configuration audits cannot answer these. The container can be entirely valid — correct tags, no orphans, clean naming — while the numbers coming out of it are wrong. That failure only becomes visible when two systems are put side by side.
How to run it
python skills/conversion-reconcile/scripts/reconcile.py \
--platform ga4_conversions.csv \
--crm crm_deals.csv \
[--key transaction_id] [--json]
What each file needs. A shared identifier is the only hard requirement: a transaction
id, order id, lead id, deal id or click id present on both sides. The column is
auto-detected; pass --key when the shared column uses an unusual name or the guess is
wrong. If the two exports use different headers for the same identifier, rename those
headers to one shared name in copies of the exports first.
Everything else is optional and each one buys another detector:
| Column | What it unlocks |
|---|---|
| a date on both sides | timezone and attribution-window mismatch, step changes |
page_path or landing_page |
a trigger firing on pages it should not |
event_name or conversion_action |
one event double-counted while the rest are fine |
source / medium / campaign |
excess concentrated on paid traffic |
What it looks for
Each detector matches a shape, not a number, and every one reports the evidence that fired it:
| Cause | Signature |
|---|---|
join_key_mismatch |
Both sides are mostly strangers. Ranked first when it fires, because every other diagnosis is noise until the join works. |
duplicate_events |
The same id appears more than once on the platform side, usually exactly twice. |
trigger_matching_too_broadly |
The excess piles onto one page path or one event, while everything else reconciles. |
timezone_or_window_mismatch |
Totals agree, days do not, and shifting one side by a day collapses the disagreement. |
step_change_on_a_date |
The ratio was stable, then changed, and never went back. |
duplicate_stream_or_container |
Everything is inflated by the same round multiple, evenly, across unrelated dimensions. |
platform_undercount |
The CRM has conversions the platform never saw. |
Reading the output
Diagnoses are ranked by how well the divergence fits that shape — not by how likely the fix is to work, and not by severity. The confidence number is a goodness of fit.
Read the evidence line before acting on the label. Every diagnosis states the counts and shares that produced it, so it can be checked against the data rather than believed.
More than one can be true at once, and often is: a duplicated event will also produce a flat 2x ratio, so both appear, most specific first.
Silence is a real answer. When nothing fits, the tool says the two exports do not disagree in any way it can name — which is deliberately not the same claim as "your tracking is correct."
What to tell the user afterwards
- Fix the join first if
join_key_mismatchfired. Nothing else is readable until it is gone. - Take the top diagnosis to the place the evidence points, not to the whole stack. If the excess is on one path, open that one tag.
- Re-run after the fix. The ratio moving toward 1.0 is the only proof the change worked, and it is cheap to check because the tool needs nothing but two fresh exports.
- Historical data usually cannot be repaired in the platform. Say so plainly rather than implying a backfill is coming; where a warehouse export exists, the correction can be applied at query time instead.
What it will not do
- It does not connect to anything. Two CSVs, locally.
- It does not model attribution. It compares what two systems recorded about the same identified conversions, which is a different and more answerable question.
- It cannot see a conversion neither system recorded.
- It will not attribute a cause without evidence. Where the shape is ambiguous it returns several candidates rather than picking one, and where nothing fits it returns none.
Fixtures and tests
python tools/make_fixtures.py # regenerate (seeded, deterministic)
python tests/test_conversion_reconcile.py
Four synthetic scenarios ship with the repo: one clean, one with duplicated events, one with a trigger firing on a single path, one with a one-day timezone offset. The test asserts each gets the right top diagnosis and that the three faulty ones get three different ones — a detector that always answered "duplicate events" would pass a single-scenario test and be worthless.