Problem context
You have analytics events firing across the codebase but no canonical list of what they are.
Different teams disagree about what specific events mean or where they fire.
Dashboards reference event names nobody is sure exist in the current code.
What breaks if this is not solved
- New PRs silently change events because nobody knows which events the PR touches.
- Onboarding new engineers takes too long because the instrumentation is implicit.
- Decisions get made against dashboards that are partly drawn from events that no longer fire.
When this playbook applies
- Your codebase has more than a few analytics calls and you cannot list them from memory.
- You have at least one analytics library actually wired up (PostHog, Mixpanel, Segment, Amplitude, Heap, or Snowplow).
- You have not run a structured audit in the last six months.
System approach
Treat the audit output as data, not a document. The manifest should be machine-readable so future PRs can diff against it.
Audit once locally before turning anything on in CI. The first run will surface real questions about which events are obsolete.
Resolve ambiguity at audit time, not later: every event in the manifest should have an owner and a use.
Execution steps
- Install the Skene CLI: `npm install -g @skene/cli`.
- Run `npx @skene/cli audit` at the repo root. It writes a `skene-manifest.json` with every analytics call.
- Open the manifest. Group events by file or by library to see the shape of what exists.
- For each event, mark: still in use, deprecated, or unclear. Resolve the unclear ones with whoever wrote them.
- Drop the obsolete calls in a single PR. Commit the cleaned manifest.
- Decide whether to keep auditing locally, or wire up the GitHub Action so every future PR validates against the manifest.
Metrics to watch
Events in the manifest
Whatever the audit returns - this is your baseline.
A useful baseline. Not a target. Repeat the audit quarterly to track whether the surface is growing in a controlled way.
Deprecated events
Trend down to zero after the cleanup PR.
If deprecated events keep coming back, somebody is reintroducing them by copy-paste.
Failure modes
- Treating the manifest as a write-once document. It needs to live in code and update on every merge.
- Cleaning up obsolete events without checking the dashboards that depend on them.
- Auditing once, never again, and waiting six months for the surface to drift again.
