tracking-os

Tracking OS

Superseded. Do not install from here.

This repo is the 28 August 2026 packaging. The maintained version is the Tracking Planner, which ships as a plugin in the same marketplace as Discovery OS and carries the corrections made on 30 August. Install that one:

/plugin marketplace add riadchaban994-bot/discovery-os
/plugin install tracking-planner@riadchaban

Everything below describes the same skill in its older form. It is kept for history.

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/discovery-os
/plugin install tracking-planner@riadchaban

Not on Claude Code? Copy the skill folder straight in, see Quick start.

Companion to Discovery OS, which decides what to build. That pairing now lives in one marketplace, with the maintained tracking half published as the Tracking Planner.

The problem it solves

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.

Quick start

Claude Code plugin (recommended):

/plugin marketplace add riadchaban994-bot/discovery-os
/plugin install tracking-planner@riadchaban

Any agent (Claude Code, Codex, Gemini CLI, Copilot CLI, or a bare skills folder):

git clone https://github.com/riadchaban994-bot/tracking-planner.git
cp -R tracking-planner/skills/* ~/.claude/skills/   # or ~/.codex/skills/, ~/.agents/skills/

Then 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.

The evidence ladder

This is the whole idea, and everything else follows from it. Every event carries one of four grades.

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.

What it produces

A multi-tab Excel workbook, generated from a single JSON file so it can be regenerated and diffed:

How it works

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.

The scripts

Two, both tested in CI on three Python versions.

python3 scripts/validate_plan.py plan.json --platform ga4
python3 scripts/build_workbook.py plan.json

validate_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.

What it will not do

• 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.

Requirements

• Python 3.8 or newer, with openpyxl (the workbook) and Pillow (embedding screenshots)
• Optional: LibreOffice and pdftoppm for 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.

Honest limitations

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.

Licence

MIT. Use it, fork it, sell the consulting built on it. No attribution required, though it is welcome.