@inizioevoke/veeva-astroclm-core 1.1.3 → 1.1.4

package/agents/claude/analytics-auditor/SKILL.md

@@ -256,6 +256,31 @@ current page.
 7. Store all messages in `pageMessages` with the page route (e.g. `/home/`) as their
    source.
 
+8. **Flag ambiguous click data.** After collecting tracking events for the page, check
+   each event against these criteria and mark it ambiguous if **any** apply:
+
+   - **Missing or empty field** — `slide`, `type`, or `name` is absent, `null`, `""`,
+     or the literal string `"undefined"`.
+   - **Generic name** — `name` is a value like `"button"`, `"link"`, `"click"`,
+     `"undefined"`, or matches the pattern `/^(button|link|click|item|element|tab)\d*$/i`
+     with no further specificity.
+   - **Name equals type** — `name` and `type` have the same value (e.g.
+     `{ type: "button", name: "button" }`).
+   - **Duplicate (slide, name) pair on the same page** — the same `(slide, name)`
+     combination fires more than once from distinct elements on the same page, making
+     it impossible to distinguish which element the user clicked.
+   - **Slide mismatch** — the `slide` value in the event does not match the route of
+     the page it was captured on (e.g. `slide: "home"` on `/about/`).
+
+   For each ambiguous event store:
+   ```
+   {
+     page: string,       // route where it was captured
+     event: { slide, type, name },
+     reasons: string[]   // one entry per applicable criterion above
+   }
+   ```
+
 ---
 
 ### Step 4 — Parse, deduplicate, and structure the data
@@ -314,13 +339,20 @@ Everything else is a **Slide Event**.
 For global events, drop the `slide` dimension entirely — only `type` and `name` are needed.
 For slide events, retain `slide`, `type`, and `name`.
 
+#### Deduplicate ambiguous events
+
+Apply the same timestamp-stripping deduplication to the ambiguous events list. Two
+ambiguous events are duplicates if their `(page, slide, type, name)` tuples are equal —
+keep one entry but merge their `reasons` arrays (union, no duplicates).
+
 #### Tiers
 
-Organize into four tiers:
+Organize into five tiers:
 1. **Tracking Events** — messages matching the `DEBUG: track` pattern (split into Global and Slide sub-sections, see Step 5)
-2. **Errors** — `console.error`
-3. **Warnings** — `console.warn`
-4. **Info / Log** — `console.log`, `console.info`, `console.debug` (excluding tracking events)
+2. **Ambiguous Events** — tracking events that matched one or more ambiguity criteria in Step 3.8
+3. **Errors** — `console.error`
+4. **Warnings** — `console.warn`
+5. **Info / Log** — `console.log`, `console.info`, `console.debug` (excluding tracking events)
 
 ---
 
@@ -337,7 +369,7 @@ structure:
 
 **Date:** <today's date>
 **Pages audited:** /home/, /about/, /about/moa/
-**Total unique messages:** <N> tracking events (<G> global, <S> slide-specific), <E> errors, <W> warnings, <I> info/log
+**Total unique messages:** <N> tracking events (<G> global, <S> slide-specific, <A> ambiguous), <E> errors, <W> warnings, <I> info/log
 
 > **Skipped (dynamic routes):** src/pages/[slug].astro, src/pages/[...path].astro
 
@@ -365,6 +397,15 @@ feature.
 |-------|------|------|
 | `home` | `button` | `button_important_safety_information` |
 
+## Ambiguous Events (<A>)
+
+> These tracking events could not be unambiguously attributed to a specific element or
+> action. Review and correct the tracking configuration for each one.
+
+| Page | Slide | Type | Name | Reason(s) |
+|------|-------|------|------|-----------|
+| `/home/` | `home` | `button` | `button` | Generic name; Name equals type |
+
 ## Errors (<count>)
 
 | Message | Pages |
@@ -391,12 +432,41 @@ feature.
 Omit the "Skipped" blockquote if no dynamic routes were found. If a tier has zero
 messages, write `_None_` instead of a table. If there are no slide-specific events,
 write `_None_` under that sub-section. Omit the Global Events sub-section header note
-if there are no global events.
+if there are no global events. If there are no ambiguous events, write `_None_` under
+the Ambiguous Events section.
+
+After writing the Markdown file, write a CSV file to the project root using the same
+base name with the extension changed to `.csv` (e.g. `analytics-audit-report-20260616143022.csv`).
+
+The CSV contains one row per unique tracking event (global and slide, excluding
+ambiguous). Use this header and column rules:
+
+```
+slide,type,name
+```
+
+- **Global events** — set `slide` to `GLOBAL`. Use the event's own `type` and `name`.
+- **Slide events** — set `slide` to the event's `slide` value. Use `type` and `name` as-is.
+
+Output global events first (sorted by `type`, then `name`), followed by slide events
+(sorted by `slide`, then `type`, then `name`).
+
+If a field value contains a comma, double-quote, or newline, wrap it in double quotes
+and escape any internal double quotes by doubling them (`"` → `""`).
+
+Example:
+```csv
+slide,type,name
+GLOBAL,nav-button,nav-button_about_pbc
+GLOBAL,nav-button,nav-button_home
+home,button,button_important_safety_information
+about,button,button_request_info
+```
 
-After writing the file, tell the user the full filename (e.g.
-`analytics-audit-report-20260616143022.md`) and give a brief summary (e.g. "Found 8
-tracking events (5 global, 3 slide-specific), 2 errors, 1 warning, 5 info messages
-across 3 pages").
+After writing the file, tell the user both filenames and give a brief summary (e.g.
+"Found 8 tracking events (5 global, 3 slide-specific, 2 ambiguous), 2 errors, 1
+warning, 5 info messages across 3 pages"). If there are any ambiguous events, call them
+out explicitly in the summary so the user knows action is needed.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inizioevoke/veeva-astroclm-core",
-  "version": "1.1.3",
+  "version": "1.1.4",
   "description": "",
   "license": "ISC",
   "author": "",