clawfort/openspec/changes/p12-umami-events-and-more/design.md

Context

Current Umami event payloads for hero/feed CTA clicks and summary modal lifecycle events are identifier-heavy (article_id) and not directly human-readable in dashboards. Analysts must resolve IDs back to content to understand behavior patterns, which slows ad-hoc exploration and increases reporting friction.

Goals / Non-Goals

Goals:

• Add article_title to existing CTA and summary modal analytics payloads.
• Preserve existing event names and current fields for backward compatibility.
• Keep changes scoped to frontend event payload construction.

Non-Goals:

• Renaming event names or changing event timing semantics.
• Introducing new analytics providers or backend event pipelines.
• Reworking existing dashboard taxonomy outside payload enrichment.

Decisions

Decision 1: Additive payload enrichment only

Choice: Add article_title as an extra property while retaining article_id and existing metadata.

Rationale:

• Backward compatible for existing analytics queries.
• Immediate analyst readability improvement without migration burden.

Decision 2: Use headline string from the in-memory item model

Choice: Populate article_title from current article object (item.headline / modalItem.headline).

Rationale:

• No extra network calls or state plumbing.
• Data already present where events are emitted.

Decision 3: Preserve event contracts and dispatch points

Choice: Keep event names unchanged (hero-cta-click, summary-modal-open, summary-modal-close).

Rationale:

• Avoids dashboard/query breakage.
• Keeps this change low risk and auditable.

Risks / Trade-offs

• [Risk] Long titles inflate payload size -> Mitigation: send raw headline as-is; acceptable for low-volume client events.
• [Risk] Missing title on edge cases -> Mitigation: include article_id as canonical fallback identifier.
• [Trade-off] Same event schema differs across historical windows -> Mitigation: additive field keeps historical queries valid while enabling richer future segmentation.

Migration Plan

1. Update event emitters in frontend/index.html to include article_title.
2. Verify emitted payloads in browser devtools/Umami debug path.
3. Update analytics-tagging spec deltas and task checklist.

Rollback:

• Remove article_title field additions; existing events remain unchanged.

Open Questions

• Do analysts also want article_permalink included now, or defer to future UX/permalink change?