usability enhancements

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

@@ -0,0 +1,57 @@
+## 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?