The tracking plan as code

Each plan event has a when rule and a props map. The rule names the raw event type and, where one raw type hides several moments, the payload key and value that picks the right one: a CreateEvent is only "Repository Created" when ref_type == "repository", a PullRequestEvent is only "Pull Request Opened" when action == "opened". The props map is name to Python type. Nothing else. A plan this small can be read in a code review, which is most of its value.

Keeping the plan in the repository next to the code that sends events means a change to one shows up in the diff of the other. Commercial tools offer the same idea as a hosted schema with a "block unplanned events" switch; the principle is identical and the code version costs nothing.

89,490 events in the hour map to no plan event: 29,113 branch and tag creations, 15,033 deletions, 13,398 issue comments, 9,662 pull request events that are not openings, 8,515 reviews and the long tail. Printing that count, by type, every run, is what stops a plan from rotting. When the count for a type jumps, something new is being sent, and either the plan grows a row or someone asks why the product started emitting it.

Presence: is the property there at all. Type: is it an int, a string, a bool. Meaning: is it a value that fits what the event claims happened, a push with at least one commit, a price above zero, a timestamp not in the future. Most tools check the first two. The third is where product definitions live, and it has to be written by someone who knows what the event is for.

Keep meaning checks as warnings with counts, not as filters that silently drop rows. The 234 are real events. Whether they count toward "active" is a definition question for session 3, and the validator's job is to make sure the question gets asked.

GitHub adds an org object only when a repository belongs to an organisation, so "is_org" is derived from whether the key exists. That is a legitimate encoding, and a dangerous one to copy: in your own product, a property that is absent because the client failed to send it looks exactly like one absent because it does not apply. Plans should say, per property, whether absent means false or means unknown.

The rule is short: the person is a stable id; logins, emails and display names are properties of the person that can change. The build-along counts ids per login and logins per id on the real hour and finds 7 and 0. The asymmetry is the lesson: an id never splits, a label sometimes does.

For anonymous-then-known products, PostHog's documentation describes the standard mechanism: every visitor gets an anonymous id, and calling identify at login "merges the anonymous person into the identified person", so the pre-signup events join the account. Two warnings from the same docs matter to an analyst: call reset() on logout so a shared device does not merge two people, and never identify with a generic value like "null" or "guest", which PostHog blocks because it would merge strangers.

A merge rewrites the past: yesterday's "anonymous visitor who left" becomes today's "customer who browsed first". Funnels computed before and after a merge disagree for the same day, and both are correct for their moment. Freeze the definition of the population you report on, and when a number changes after the fact, check whether identity resolution moved people before assuming behaviour moved.