Skip to content
Back to search

tracking-doctor

MarketplaceWorks with Claude CodeGitHub

Explains why pixels and analytics disagree with orders, then audits consent, server events and attribution.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mavrin-xv--tracking-doctor/badge.svg)](/listings/mavrin-xv--tracking-doctor)

HTML

<a href="/listings/mavrin-xv--tracking-doctor"><img src="/api/listings/mavrin-xv--tracking-doctor/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

pip install playwright && python3 -m playwright install chromium
S=skills; E=examples/fabrikam-tea
python3 $S/event-capture/scripts/capture.py --steps $E/steps.json --serve $E/site --out capture.jsonl
python3 $S/event-audit/scripts/audit.py capture.jsonl --plan $E/plan.csv
python3 $S/consent-check/scripts/consent.py capture.jsonl --consent-step consent-accept --reject $E/capture-reject.jsonl --reject-step consent-reject
python3 $S/attribution-leaks/scripts/leaks.py --capture capture.jsonl --sources $E/exports/ga4-sources.csv --domain fabrikam-tea.example
python3 $S/count-reconcile/scripts/reconcile.py counts $E/exports/counts.csv

The example shop has nine planted problems; `examples/fabrikam-tea/README.md` lists them and which check finds each. On your own site, write a `steps.json` for your journey and copy `templates/tracking-plan.csv`. Without Playwright, record a HAR in DevTools and use `capture.py --from-har`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 15 lines
  1. {
  2. "name": "tracking-doctor",
  3. "plugins": [
  4. {
  5. "name": "tracking-doctor",
  6. "source": "./",
  7. "description": "Find and fix why pixels and analytics lie: capture what fires in a headless browser, audit it against a tracking plan, check consent, server events, attribution leaks and counts.",
  8. "version": "0.1.0"
  9. }
  10. ],
  11. "owner": {
  12. "name": "Artem Mavrin",
  13. "url": "https://github.com/mavrin-xv"
  14. }
  15. }
README.md · README · 125 lines
  1. ![tracking-doctor](assets/banner.png)
  2. # tracking-doctor
  3. **Find out why your pixels and analytics disagree with your orders, and fix it: capture what really fires, audit it against a plan, then check consent, server events, attribution leaks and counts.**
  4. GA4 says 52 purchases, the shop says 40, Meta says 61, a third of the traffic is Unassigned, and nobody can say which number to trust or since when.
  5. [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
  6. ![Works with](https://img.shields.io/badge/works%20with-Claude%20Code%20%7C%20Codex%20%7C%20any%20SKILL.md%20agent-black)
  7. ![Python](https://img.shields.io/badge/scripts-Python%203.8%2B%20stdlib%2C%20Playwright%20for%20capture-green)
  8. ```bash
  9. git clone https://github.com/mavrin-xv/tracking-doctor && cd tracking-doctor
  10. ./install.sh # or: ./install.sh --project
  11. ```
  12. <!-- install-notes:start -->
  13. Other ways in: as a Claude Code plugin, run `/plugin marketplace add mavrin-xv/tracking-doctor` and then `/plugin install tracking-doctor@tracking-doctor`. For Codex or another agent that reads `SKILL.md`, copy the folders under `skills/` into its skills directory. On Windows, run `install.sh` from Git Bash or WSL and type `py -3` where these docs say `python3`.
  14. <!-- install-notes:end -->
  15. Then say "capture the tracking on https://your-site.example and audit it".
  16. ---
  17. ## What it solves
  18. | Pain | Fix in this repo |
  19. |---|---|
  20. | Purchases are counted twice, revenue looks better than the bank account | `capture.py` reloads the thank-you page; `audit.py` flags every order id sent twice and every second tag |
  21. | Nobody knows what the tags really send | a headless browser walks the journey and records every GA4, Google Ads, Meta, PostHog, TikTok, LinkedIn and UET request |
  22. | The pixel fires before the cookie banner, or nothing fires after Accept | `consent.py` splits the capture at the banner click and checks hits, `gcs` signals and cookies on both sides |
  23. | Server events get a 200 and never show up | `mp_check.py` lints GA4 Measurement Protocol and PostHog payloads and calls the GA4 debug endpoint |
  24. | A third of sessions are Unassigned, PayPal is a top referrer | `leaks.py` follows click ids through redirects and lints the source / medium export |
  25. | Three tools, three numbers | `reconcile.py` compares each tool with the backend by day and by order id, and says which gap is a bug |
  26. | A release breaks tracking and nobody notices for a month | `checklist.py` turns the plan into a release test; the scripts exit 1 so CI goes red |
  27. ## What's inside
  28. | Skill | What it does | Say |
  29. |---|---|---|
  30. | `event-capture` | Headless browser journey (or a HAR file) to a record of every tracking request | "capture what my pixels send", "is purchase firing" |
  31. | `event-audit` | Capture against tracking plan: missing, doubled, params, order ids, currency, PII | "audit my events", "GA4 shows more purchases than orders" |
  32. | `consent-check` | What fires before and after Accept and Reject, Consent Mode basic or advanced | "does my cookie banner work", "consent mode v2 check" |
  33. | `server-events` | Lint and validate GA4 Measurement Protocol and PostHog payloads | "server events don't show up", "send purchases from the backend" |
  34. | `attribution-leaks` | Lost click ids and UTMs, payment and self referrals, Unassigned share | "why is so much traffic Unassigned", "check my UTMs" |
  35. | `count-reconcile` | Tools against the backend by day and by order id | "GA4 and the shop don't match", "which number is right" |
  36. | `tracking-qa` | Release test checklist from the plan, plus a CI job | "test tracking before release", "add tracking tests to CI" |
  37. ## Quick start
  38. ```bash
  39. pip install playwright && python3 -m playwright install chromium
  40. S=skills; E=examples/fabrikam-tea
  41. python3 $S/event-capture/scripts/capture.py --steps $E/steps.json --serve $E/site --out capture.jsonl
  42. python3 $S/event-audit/scripts/audit.py capture.jsonl --plan $E/plan.csv
  43. python3 $S/consent-check/scripts/consent.py capture.jsonl --consent-step consent-accept --reject $E/capture-reject.jsonl --reject-step consent-reject
  44. python3 $S/attribution-leaks/scripts/leaks.py --capture capture.jsonl --sources $E/exports/ga4-sources.csv --domain fabrikam-tea.example
  45. python3 $S/count-reconcile/scripts/reconcile.py counts $E/exports/counts.csv
  46. ```
  47. The example shop has nine planted problems; `examples/fabrikam-tea/README.md` lists them and
  48. which check finds each. On your own site, write a `steps.json` for your journey and copy
  49. `templates/tracking-plan.csv`. Without Playwright, record a HAR in DevTools and use
  50. `capture.py --from-har`.
  51. ## How it works
  52. ```text
  53. steps.json ─► capture.py ─► capture.jsonl ─┬─► event-audit what fired vs the plan
  54. (or a HAR) requests answered locally, ├─► consent-check before and after the banner
  55. nothing reaches vendors └─► attribution-leaks click ids, UTMs, referrals
  56. payload.json ──────────────────────────────────► server-events lint + GA4 debug endpoint
  57. counts.csv, orders, exports ───────────────────► count-reconcile tools vs backend
  58. plan.csv ──────────────────────────────────────► tracking-qa release checklist, CI gate
  59. ```
  60. Order: capture first, because every other judgement needs to know what really fired. Fix
  61. doubles and PII before missing events, then consent, then leaks, and measure the result with
  62. count-reconcile a day later. Details in `docs/how-it-works.md`.
  63. ## Configure
  64. | Setting | Where | Default |
  65. |---|---|---|
  66. | Journey | `steps.json`: goto, click, fill, reload, wait | none |
  67. | Send to vendors | `capture.py --live` | off: tracking requests answered locally |
  68. | Proxy hosts | `capture.py --posthog-host`, `EXTRA_POSTHOG_HOSTS` in `trackhits.py` | PostHog cloud hosts |
  69. | Consent mode | `consent.py --mode basic or advanced`, `--expect` vendors | advanced; ga4, meta, posthog |
  70. | GA4 debug | `GA4_MEASUREMENT_ID`, `GA4_API_SECRET` environment variables, `--region eu` | lint only |
  71. | Bands | `reconcile.py --over --under --drift` | 1.05, 0.70, 15 points |
  72. | Unassigned limit | `leaks.py --not-set-max` | 5% |
  73. ## Honest limits
  74. - Browser tracking request formats (`/g/collect`, Meta `/tr`, `gcs`, `gcd`) are not documented by the vendors. The patterns match what tags send today and can break; `skills/event-capture/references/vendor-patterns.md` says which are verified.
  75. - A capture sees one journey in one browser. It cannot see blocked visitors, other devices or what the vendor drops after receiving.
  76. - Meta CAPI payloads and browser against server dedup are not covered here; the eid is only checked for presence.
  77. - The channel rules in `leaks.py` are a simplified copy of GA4's default channel group.
  78. - Bands in `reconcile.py` and the 5% Unassigned limit are working rules, not vendor limits.
  79. - consent-check reports what fires. It is not legal advice.
  80. - Tested: every script on the invented example, live captures of the example site, two public sites captured with tracking requests answered locally, a HAR import, and the GA4 debug path against a local mock. Not tested by us: the real GA4 debug endpoint, PostHog ingestion, sites behind a login, server-side GTM, Safari and Firefox engines.
  81. - Tested with Claude Code. Other agents that read SKILL.md files should work; not tested.
  82. ## Credits
  83. - https://github.com/petrkindlmann/qa-skills (MIT): the analytics tracking testing method (intercept tracking requests rather than read the DOM, parse query and body, validate against an external plan and report all violations, test consent as an input, fail CI on a dropped event and prove the gate by breaking it). Rewritten, no text copied.
  84. - https://github.com/coreyhaines31/marketingskills (MIT): object_action naming, the checklist of values populated, no duplicates and no PII, auditing UTMs after redirects, and symptom triage. Rewritten, no text copied.
  85. - Google Analytics Measurement Protocol docs (reference, validation, limits), Google tag consent docs, GA4 help "Default channel group" and the Unassigned definition.
  86. - PostHog capture API docs. Meta docs on deduplicating Pixel and Conversions API events.
  87. - Neighbour packs, not duplicated here: `meta-capi` in ads-creative-lab (CAPI build and dedup), `tracking-plan` and `traffic-diagnosis` in marketing-analytics-hub (UTM builder, naming linter), `conversion-cleanup` in google-ads-doctor (conversion action settings).
  88. ## Contributing
  89. See `CONTRIBUTING.md`. Coding agents should read `AGENTS.md` first.
  90. <!-- author:start -->
  91. ## Author
  92. Built and maintained by [Artem Mavrin](https://github.com/mavrin-xv). This repo is one of a set of agent skill packs for marketing and operations work. Each one installs on its own; the full list is in [agent-skill-packs](https://github.com/mavrin-xv/agent-skill-packs). If a pack saved you an afternoon, a star helps other people find it.
  93. <!-- author:end -->
  94. ## License
  95. MIT, see `LICENSE`.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.