Event Tracking Skill

1---
2name: event-tracking-skill
3description: Use when the request is end-to-end, spans multiple workflow phases, or the correct tracking-workflow entry point is still unclear.
4---
5 
6# Event Tracking Skill
7 
8Use this skill as the umbrella router for the GA4 + GTM tracking system.
9 
10Use it when:
11 
12- the request is end-to-end
13- the request spans multiple phases
14- the correct workflow entry point is still unclear
15 
16Do not assume the user wants the full workflow.
17 
18<!-- event-tracking auto-update bootstrap:start -->
19## Auto-Update
20 
21This installed root skill can self-check for newer GitHub versions before you continue.
22 
23Before doing any task in this bundle:
24 
251. Resolve the directory that contains this installed `SKILL.md`. For Codex installs it is usually `$CODEX_HOME/skills/event-tracking-skill` or `~/.codex/skills/event-tracking-skill`.
262. Run `node "<bundle-dir>/runtime/skill-runtime/update-check.mjs" --json`.
273. If the result status is `update_available`, immediately run `node "<bundle-dir>/runtime/skill-runtime/self-update.mjs" --apply`.
284. If the update succeeds, read `<bundle-dir>/SKILL.md` again before continuing so you are using the refreshed instructions.
295. If the result status is `disabled`, treat this bundle as a local development link or repo checkout and continue without updating.
30 
31<!-- event-tracking auto-update bootstrap:end -->
32 
33## Skill Family
34 
35The skill family is split into one umbrella skill plus seven phase skills:
36 
37- `tracking-discover` for crawl coverage, platform detection, and fresh artifact bootstrap
38- `tracking-group` for page-group authoring and approval
39- `tracking-live-gtm` for auditing the real live GTM runtime before schema generation
40- `tracking-schema` for schema preparation, review, validation, and approval
41- `tracking-sync` for GTM config generation and sync
42- `tracking-verify` for preview QA and optional publish handoff
43- `tracking-shopify` for Shopify-specific schema, sync, install, and verification rules
44 
45If the request is already bounded to one phase and that phase skill is available, route there instead of inlining the full runbook here.
46 
47Once `site-analysis.json` indicates Shopify, keep discovery and grouping shared, then let `tracking-shopify` own the Shopify-specific branch.
48 
49## Shared Contract
50 
511. Use the repo-local wrapper `./event-tracking` for CLI commands in this repository. If the wrapper reports that `dist/cli.js` is missing, run `npm run build` first.
522. Keep one artifact directory per site (`<output-root>/<url-slug>`). Each iteration inside that artifact should use a distinct run ID with snapshots under `versions/<run-id>/`.
533. If the user already provides an artifact directory or one of its files, resume from the earliest unmet prerequisite instead of restarting from `analyze`.
544. Use `./event-tracking status <artifact-dir-or-file>` whenever the current checkpoint or next step is unclear.
555. Use `./event-tracking runs <output-root>` when the user wants to find recent site runs and does not remember the artifact directory.
566. Google OAuth client metadata is embedded in the CLI and may be overridden with `GOOGLE_OAUTH_CLIENT_ID` / `GOOGLE_OAUTH_CLIENT_SECRET`.
577. Any Playwright-backed or OAuth-triggering step must run outside a sandboxed environment by default. In practice, treat `analyze`, `validate-schema --check-selectors`, `preview`, and `sync` as non-sandbox commands, and do not first attempt them in the sandbox before retrying after interception.
588. Never auto-select a GTM account, GTM container, or GTM workspace on the user's behalf. Always show candidates and require explicit confirmation unless the user already provided the exact ID for that step.
599. Prefer scenario-first entry commands for user-facing flows: `run-new-setup`, `run-tracking-update`, `run-upkeep`, `run-health-audit`. Use `start-scenario` when the user wants a labeled scenario run without immediate template execution.
6010. Use `./event-tracking scenario <artifact-dir> --set <scenario> [--sub-scenario ...] [--new-run]` for metadata-only adjustments when you should not alter execution flow.
6111. Use `./event-tracking scenario-check <artifact-dir>` when the question is "is this scenario ready" rather than "what is the next workflow checkpoint".
6212. Use `./event-tracking scenario-transition <artifact-dir> --to <scenario> [--reason ...]` when the user wants an auditable handoff between scenarios.
6313. Do not continue past the phase boundary the user asked for. Stop after the requested phase unless the user explicitly asks to continue.
64 
65## Conversation Intake
66 
67When the user enters through chat and has not yet provided a bounded phase, artifact directory, or exact command, start with an intent-first intake.
68 
69Classify the request into one of these entry intents:
70 
71- `resume_existing_run`: the user already has an artifact directory or one of its files; inspect the artifacts and use `status`
72- `new_setup`: net-new tracking implementation from scratch; prefer `run-new-setup`, then follow its recommended next step
73- `tracking_update`: revise or extend an existing implementation; prefer `run-tracking-update`
74- `upkeep`: routine maintenance, review, or incremental QA on an existing setup; prefer `run-upkeep`
75- `tracking_health_audit`: audit-only assessment of current live tracking; prefer `run-health-audit`
76- `analysis_only`: crawl/bootstrap/discovery only without committing to the full workflow yet; route to `tracking-discover` and stop after `analyze`
77 
78Rules:
79 
80- Do not ask the user to choose between `scenario` and `analyze`. `scenario` is run-intent orchestration metadata; `analyze` is only one execution step.
81- If intent is ambiguous, ask one short plain-language intake question using user-facing terms such as "new setup", "update existing tracking", "upkeep", "health audit", "analyze only", or "resume an existing run".
82- If the user gives a fresh URL and asks to set up tracking, default to `new_setup`.
83- If the user gives a fresh URL and only asks to inspect the site, analyze structure, or review current tracking signals, default to `analysis_only`.
84- If the user gives an artifact directory or workflow file, default to `resume_existing_run` instead of restarting from `analyze`.
85 
86## Routing Rules
87 
88Route by user intent and current artifacts:
89 
90- fresh URL, crawl request, or no artifacts yet: start with `tracking-discover`
91- `site-analysis.json` with missing or unconfirmed `pageGroups`: route to `tracking-group`
92- confirmed `site-analysis.json` with detected live GTM container IDs but no live baseline review yet: route to `tracking-live-gtm`
93- confirmed `site-analysis.json` or an in-progress `event-schema.json`: route to `tracking-schema`
94- `gtm-config.json`: route to `tracking-sync`
95- `gtm-context.json`: route to `tracking-verify`, with publish treated as a separate explicit action
96- Shopify platform confirmation: keep shared early stages, then hand off to `tracking-shopify`
97 
98If only the root skill is available, follow the same routing logic directly and stop at the matching phase boundary.
99 
100## Stop Rules
101 
102- Do not bypass page-group approval before `prepare-schema`.
103- For key decision checkpoints, always require explicit user confirmation before continuing:
104  - `pageGroups` (before `confirm-page-groups` and before `prepare-schema`)
105  - `event-schema.json` (before `confirm-schema` and before `generate-gtm`)
106  - GTM target selection (account/container/workspace during `sync`)
107  - publish decision (before `publish`)
108- If confirmation is missing or ambiguous, stop and ask; do not auto-proceed.
109- When live GTM containers are detected on the site, do not bypass the live baseline review before schema generation.
110- Do not bypass schema approval before `generate-gtm` unless the user explicitly wants `--force`.
111- Treat preview QA and publish as separate decisions.
112- Treat `tracking-health.json` as the publish gate; do not jump to publish when health is missing, manual-only, or blocked unless the user explicitly wants `--force`.
113- Treat Shopify manual verification as the expected path for Shopify runs, not as a fallback error case.
114- Treat `tracking_health_audit` as an audit-only scenario. Do not run GTM deployment actions (`generate-gtm`, `sync`, `publish`) unless the user explicitly asks to override.
115 
116## Resume And Closeout
117 
118When resuming:
119 
120- prefer `workflow-state.json` when present
121- still inspect the real artifact set if warnings indicate stale gates
122- use `status` when the next step is unclear
123 
124When a phase or the full workflow ends, summarize:
125 
126- artifact directory
127- current checkpoint from `workflow-state.json`
128- key output files from the completed phase
129- next recommended command, if any
130- remaining manual actions, especially for custom dimensions, Shopify install, tracking health, preview QA, or publish approval
131 
132## References
133 
134- [skill-map.md](references/skill-map.md) for the umbrella / phase skill map
135- [architecture.md](references/architecture.md) for lifecycle, checkpoints, and resume semantics
136- [output-contract.md](references/output-contract.md) for artifact files and gate semantics
137- [shopify-workflow.md](references/shopify-workflow.md) for Shopify-specific branch expectations
138