Build a tracking plan from what your app actually does, not from what you remember it doing.
A skill that turns Claude Code, Codex, Copilot CLI or Gemini CLI into something that will open your app, walk every journey, screenshot every surface, and write the tracking plan from what it saw. Then tell you plainly which parts it saw and which parts it made up.
Free, MIT, no accounts, no telemetry. Built as a giveaway for ProductTank Syria, Damascus, 2026.
/plugin marketplace add riadchaban994-bot/tracking-os
/plugin install tracking-os@riadchabanNot on Claude Code? One line: curl -fsSL .../install.sh | bash
Companion to Discovery OS, which decides what to build. This one decides what to measure once you have built it.
Most tracking plans are written in a document, from memory, by someone who has not opened the app in a month. They look authoritative. They are quietly wrong in ways nobody notices until the data arrives a quarter later and somebody asks why the funnel does not add up.
The failure is specific and it repeats:
- Events that describe a screen that does not exist, or fire at a moment the app never reaches.
- Enum values invented wholesale. Cancellation reasons, error codes, payment states, all typed confidently into a spreadsheet by someone who never saw a cancellation. An engineer builds the enum. It can never be populated. An analyst queries it, gets nothing, and concludes tracking is broken.
- A plan so large nobody builds it. A hundred and twenty events handed to a team already running at capacity is not a plan, it is a wish.
- No way to tell fact from proposal. Every row in the same typeface, so the fifteen rows that needed a ten-minute conversation with a backend engineer instead become a sprint spent building something that cannot work.
This fixes that by refusing to write a single event from memory, and by grading every row by how strong the evidence behind it actually is.
Claude Code plugin (recommended):
/plugin marketplace add riadchaban994-bot/tracking-os
/plugin install tracking-os@riadchabanAny agent (Claude Code, Codex, Gemini CLI, Copilot CLI, or a bare skills folder):
curl -fsSL https://raw.githubusercontent.com/riadchaban994-bot/tracking-os/main/install.sh | bashThen say what you need:
/tracking-plan walk the app and build a plan from what is there
/tracking-audit audit an existing plan or live setup, produce the delta
/tracking-feature design the events for one feature before it ships
Or just describe the situation. The skill triggers on its own.
This is the whole idea, and everything else follows from it. Every event carries one of four grades.
| Grade | Meaning |
|---|---|
| OBSERVED | The surface was seen in the running app, and so was the moment the event fires. A screenshot exists. |
| PARTIAL | The surface was seen but a branch was never exercised. The event is real; some of its values are not confirmed. |
| INFERRED | Never seen. Designed from convention, a platform's standard taxonomy, or a document. Legitimate. Presenting it as observed is not. |
| UNVERIFIABLE | Cannot be checked without a real transaction, a paid subscription, or a feature that has not launched. |
The workbook states its own distribution on the cover, so anyone opening it knows what kind of document they are holding before they read a row.
Why this matters more than it sounds like it should. A plan that says "we are unsure about these fifteen events" converts into a one-hour workshop that closes them. A plan that hides the same uncertainty converts into a sprint. The uncertainty did not disappear when you hid it. It moved to a more expensive place to find it.
A multi-tab Excel workbook, generated from a single JSON file so it can be regenerated and diffed:
| Tab | What it is |
|---|---|
| Read me | Architecture, conventions, identity, privacy, platform limits, rollout |
| Phase 1 build ask | The deliverable. Only what to build now, with source, evidence, screens, effort |
| Roadmap | Phase 2 and 3, what earns each, and what was cut with the reason |
| Attribute packs | Every parameter: required, conditional or optional, with type and values |
| All events | The full target state, phased and graded |
| User properties | Persistent attributes and their update rules |
| Custom definitions | What to register before shipping, derived from the packs so it cannot drift |
| Key events & audiences | Conversions and standing segments |
| Journey funnels | Ordered event sequences per KPI |
| Gaps closed | Each known problem mapped to the event that fixes it |
| Journey map | Screen-by-screen record of the walkthrough |
| Confirm before build | What is designed rather than observed, and what to ask engineering |
| Screen gallery | Every screenshot embedded, with reverse lookup to the events |
It walks the app. Android emulator through adb, iOS simulator, a browser, or a Figma file for
designs that have not shipped. It screenshots every surface and records both what the user sees and
what the app does, because only the second tells you where an event fires.
It groups parameters into attribute packs. Reusable bundles, defined once and attached by the events that need them, instead of the same parameter written thirty times with four slightly different descriptions. A starter library covers ten industries with realistic sample values.
It consolidates. Six order-status events become one event with a status parameter, which turns six backend integration points into one hook. This is where a 120-event plan becomes a 79-event plan without losing a single answer. Four categories of merge are forbidden, and it knows which.
It phases. An event enters Phase 1 only if it fixes something already broken, or is required for a KPI the business is measured on, or is the only measurement point of a leak already costing money.
It marks the work. Every event says FE, BE, FE + BE or SDK, so the mobile ticket and the backend ticket separate cleanly, and every parameter says whether its absence is a bug or a non-event.
Two, both tested in CI on three Python versions.
python3 scripts/validate_plan.py plan.json --platform ga4
python3 scripts/build_workbook.py plan.jsonvalidate_plan.py knows the limits for GA4, Amplitude, Mixpanel, PostHog and Segment, reads which
one you are on from meta.destination, and honours account-level quotas you state in meta.limits.
It checks event names against that platform's rules, parameter budgets against its
caps, quotas, attachment integrity, dead cross-references left behind by merges, missing evidence
grades, prose counts that disagree with the data, event names still referenced after being merged
away, and the trap where a value beginning with = is silently parsed as a spreadsheet formula. It
also warns when no event is graded OBSERVED, so a plan written from a description cannot quietly
present itself as evidence-based.
It separates blockers from warnings and exits non-zero on blockers, so it drops into CI.
build_workbook.py turns the JSON into the workbook: styling, evidence colour-coding, embedded
screenshots with internal links, computed row heights, print setup. The tables that could drift are
derived from the source rather than hand-maintained.
- Write an event from memory. If it did not see the surface, it says so in the Evidence column.
- Transact on your behalf. It walks to the commit button and stops. No orders, no payments, no credentials entered for you. Everything past that button is graded UNVERIFIABLE and declared.
- Invent an enum and present it as fact. Values it could not observe are marked, and the "Confirm before build" tab lists them with the question to ask engineering.
- Hand you 120 events and call it a plan. It phases, and it argues for the phasing.
- Python 3.8 or newer, with
openpyxl(the workbook) andPillow(embedding screenshots) - Optional: LibreOffice and
pdftoppmfor the render-and-look QA step, which is the step that catches what source inspection cannot - To walk a live app: an Android emulator with
adb, an iOS simulator, browser automation, or a Figma file. Any one is enough. With none of them it still works from a description, and grades everything accordingly.
Version one, built from one deep engagement. The scripts are covered by CI and the whole skill was put through a cold-run test by an agent that had never seen it, which found a hard crash, an unreachable reference file, three documentation contradictions and four checks the validator claimed to make and did not. Those are fixed. It has still not been run across dozens of real products, so expect it to meet situations it does not handle. If it breaks on yours, open an issue with what you asked for and what it produced. That feedback is what makes version two good.
It does not connect to your analytics tool. It produces the plan and the spec; implementing and verifying the events is still a job for your engineers, and the plan is written to make that job small rather than to pretend it is done.
MIT. Use it, fork it, sell the consulting built on it. No attribution required, though it is welcome.