Tracking Architect: 5W1H Type-Safe Event Taxonomy & Data Contracts

This skill exists to stop: designing new events without checking the existing contract — spawning a third naming convention and fragmenting data (a failure that actually happened; see rationalization T5).

📁 Source note: [sage] = upstream Sage repo (github.com/xoai/sage, public) — optional deeper reading; this skill runs fully on the rules inlined here. A step marked MUST READ points at a file in your own project (e.g. an event registry) — if it is missing, stop and ask instead of improvising.

🤖 0. HOW TO USE (agent workflow)

A. Add a new event: MUST READ the event registry + tracking contract first — extend the existing taxonomy, never invent a new naming scheme. Map the 5W1H semantics and versioning policy to that contract; preserve existing field names, optionality, identity rules, and supported schema versions. If the required registry is missing, ask for it before finalizing an extension; a labeled proposal can still identify the gap. B. Audit tracking: reconcile emitted events against the registry; report status against the runtime verification gates ("spec'd" ≠ "verified"). Output: item → status → missing gate. C. Funnel SQL: use production evidence for production claims; exclude QA/bot traffic and unsupported schema versions. Synthetic examples may demonstrate a query but must be labeled and cannot verify a live funnel. MUST: every tracking claim declares its verification status; an absent metric is absent, never zero.

🏛️ 1. Core Architecture: Mapping 5W1H to the Existing Contract

Use 5W1H to check which context each event needs, not to impose a universal envelope. The diagram is an edtech TypeScript/Zod example; adapt its fields, naming, and validation to the target registry and stack. Record intentional omissions and version compatibility.