add-analytics-event

name	add-analytics-event
description	Instrument analytics for a new or changed user action: classify each UiEvent's analytics decision, add the event to the catalog (docs/analytics), and add the name/param constants. Use whenever adding or modifying a feature, screen, dialog, or any user-facing action/interaction.

Add analytics event

This skill makes sure a new user action ships with analytics, following the conventions in docs/analytics/README.md. It does not duplicate those conventions — read that README (naming, standard parameter dictionary, tiers, and the "Explicitly not tracked" list) and follow it exactly.

The compiler already forces the decision: every UiEvent case must declare an analytics member (it implements the UiEvent marker in ui/utils/.../presentation/UiEvent.kt), so a missing decision is a build error. This skill guides which decision to make and keeps the docs catalog in sync (the part the compiler can't check).

Workflow

For each user action added or changed (each UiEvent case):

1. Decide whether it needs an event

• If it isn't a user action at all — continuous scroll signals, animation-completion callbacks, VM lifecycle hooks, incoming messages/snackbar bridges (see the "Explicitly not tracked" section of the analytics README) → classify as EventAnalytics.NotTracked and stop here.
• Otherwise it needs an event — continue, even if the action also navigates (opens a screen/dialog/sheet, goes back, switches a bottom tab) or seems low-value (a menu open/close, a retry button, an intermediate picker step). There is no "covered by navigation" or "too minor to matter" opt-out: every discrete user click gets its own event. A click and the destination_view it triggers are different funnel signals (click-through rate vs. screen-view rate). Never classify a real user click as NotTracked; if it isn't trackable yet, that's a gap to fix now, not a reason to leave it untracked. NotTracked is reserved for things that are not clicks at all.

2. Name the event and its parameters

Follow the naming conventions (snake_case <object>_<action>, past tense; GA4 limits). Reuse existing parameters from the standard parameter dictionary where possible.

• Add the event name as a const val in core/provider/analytics/.../domain/model/AnalyticsEventNames.kt.
• Add any genuinely new parameter keys as const val in core/provider/analytics/.../domain/model/AnalyticsParams.kt.

3. Classify the UiEvent case

Pick one EventAnalytics variant (core/provider/analytics/.../domain/model/EventAnalytics.kt). Every tracked event is a Track, which splits on how it's emitted:

• Track.Automatic(name, params) — use when the event name and all params are known from the event object itself (its own fields or constants). The base TrackedViewModel emits it automatically; do not add a manual trackEvent(...) call for it.
• Track.Manual(names) — use when a param only exists after a domain call (e.g. is_read is the result of a toggle) or depends on UiState. Keep the explicit trackEvent(...) call inside the handleEvent branch. names must list every event the branch may actually emit for that case — the enforcement test (step 5) checks each one is really wired to a trackEvent call, so an incomplete or wrong names set fails the build.

Example (feature/more): OnItemClick carries its type, so its params are static → Track.Automatic. Example (feature/read): ToggleReadStatus needs the post-toggle is_read → Track.Manual(AnalyticsEventNames.CHAPTER_READ_TOGGLED).

4. Update the catalog

• Create docs/analytics/events/<event_name>.md following the template of the existing event files (Tier/Domain header, When it fires, Trigger source, Parameters, Notes).
• Add the event to the index table in docs/analytics/README.md, in its domain section.

5. Verify

Compile the affected module (./gradlew :feature:<name>:compileCommonMainKotlinMetadata) and run ./gradlew :feature:<name>:ktlintFormat. A missing analytics declaration fails the build.

Then run ./gradlew :core:provider:analytics:jvmTest — AnalyticsCatalogTest fails if a Track.Manual name isn't wired to an actual trackEvent call in the same module, or if any Track.Automatic/Track.Manual name is missing its docs/analytics/events/<name>.md entry.