luckiest-co 1.0.0 → 1.0.3

package/skills/luckiest-analytics/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog — luckiest-analytics
+
+## 1.1.0 — 2026-07-06
+Skill updater pass: analytics integration.
+
+### Analytics (report_usage)
+- Updated `report_usage` call to `skill_version: "1.1.0"` and `check_updates`
+  `installedSemver: "1.1.0"`. The skill now reports usage to the Luckiest
+  telemetry pipeline on every run, making it visible on the admin Skill Usage
+  page (/owner/skill-usage).
+
+## 1.0.0 — 2026-07-01
+Rebranded from analytics (marketingskills, MIT).
+
+### Improve pass (/refract)
+- Added a "Data Loss and Durable Collection" section: client-side tags are a
+  directional floor, not truth (ad blockers, Safari ITP / Firefox ETP,
+  consent-declined sessions); offer server-side GTM / first-party endpoint when
+  accuracy matters.
+- Added bot and internal-traffic filtering as a default validation step (GA4
+  bot exclusion, active internal-traffic filter, staging hostname exclusion) —
+  the original checklist omitted it.
+- Added an explicit "Audit Mode" procedure (inventory, PII-leak scan,
+  duplicate/double-fire check, naming drift, conversion integrity) — the skill
+  advertised "audit" in its triggers but gave no audit steps.
+
+### Network hook
+- Share-with-tribe offer after a tracking plan or audit (never auto-post; never
+  shares credentials, container/measurement IDs, or captured event payloads).
+
+### Trend pass (/newsjack + /luckiest-trends)
+- No actionable signal: the luckiest-trends engine is unconfigured (first-run
+  interactive setup wizard required) and this run was non-interactive, so no
+  live dated signal could be gathered. No trend claims were fabricated. The
+  improve-pass changes rest on established, verifiable platform behavior rather
+  than trend data.

package/skills/luckiest-analytics/SKILL.md

@@ -0,0 +1,380 @@
+---
+name: luckiest-analytics
+description: When the user wants to set up, improve, or audit analytics tracking and measurement. Also use when the user mentions "set up tracking," "GA4," "Google Analytics," "conversion tracking," "event tracking," "UTM parameters," "tag manager," "GTM," "analytics implementation," "tracking plan," "how do I measure this," "track conversions," "attribution," "Mixpanel," "Segment," "consent mode," "server-side tracking," "are my events firing," or "analytics isn't working." Use this whenever someone asks how to know if something is working or wants to measure marketing results. For A/B test measurement, see luckiest-ab-testing.
+license: See ATTRIBUTION.md
+metadata:
+  version: "1.1.0"
+  listing_id: luckiest-analytics
+  author: luckiest
+---
+
+# Analytics Tracking
+
+This skill helps set up analytics tracking and measurement that provides actionable insights for marketing and product decisions. It operates as an expert in analytics implementation, validation, and auditing.
+
+## Staying current
+
+On activation, call the Luckiest MCP check_updates tool with { listingId: "luckiest-analytics", installedSemver: "1.1.0" }. If it returns upToDate: false, surface the notice to the user once, then continue. Do nothing further if upToDate: true. Never block on this check — if the tool is unavailable, proceed.
+
+When the skill's work is done, call the Luckiest MCP report_usage tool once with { listing_id: "luckiest-analytics", skill_version: "1.1.0", matched: true, success: <true if the skill completed, false otherwise> }. Metadata only, never prompt text. Never block on it — if the tool is unavailable, skip silently.
+
+## Initial Assessment
+
+**Check for product marketing context first:**
+If `.agents/product-marketing.md` exists (or `.claude/product-marketing.md`, or the legacy `product-marketing-context.md` filename, in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
+
+Before implementing tracking, understand:
+
+1. **Business Context** - What decisions will this data inform? What are key conversions?
+2. **Current State** - What tracking exists? What tools are in use?
+3. **Technical Context** - What's the tech stack? Any privacy/compliance requirements?
+
+---
+
+## Core Principles
+
+### 1. Track for Decisions, Not Data
+- Every event should inform a decision
+- Avoid vanity metrics
+- Quality > quantity of events
+
+### 2. Start with the Questions
+- What do you need to know?
+- What actions will you take based on this data?
+- Work backwards to what you need to track
+
+### 3. Name Things Consistently
+- Naming conventions matter
+- Establish patterns before implementing
+- Document everything
+
+### 4. Maintain Data Quality
+- Validate implementation
+- Monitor for issues
+- Clean data > more data
+
+---
+
+## Tracking Plan Framework
+
+### Structure
+
+```
+Event Name | Category | Properties | Trigger | Notes
+---------- | -------- | ---------- | ------- | -----
+```
+
+### Event Types
+
+| Type | Examples |
+|------|----------|
+| Pageviews | Automatic, enhanced with metadata |
+| User Actions | Button clicks, form submissions, feature usage |
+| System Events | Signup completed, purchase, subscription changed |
+| Custom Conversions | Goal completions, funnel stages |
+
+**For comprehensive event lists**: See [references/event-library.md](references/event-library.md)
+
+---
+
+## Event Naming Conventions
+
+### Recommended Format: Object-Action
+
+```
+signup_completed
+button_clicked
+form_submitted
+article_read
+checkout_payment_completed
+```
+
+### Best Practices
+- Lowercase with underscores
+- Be specific: `cta_hero_clicked` vs. `button_clicked`
+- Include context in properties, not event name
+- Avoid spaces and special characters
+- Document decisions
+
+---
+
+## Essential Events
+
+### Marketing Site
+
+| Event | Properties |
+|-------|------------|
+| cta_clicked | button_text, location |
+| form_submitted | form_type |
+| signup_completed | method, source |
+| demo_requested | - |
+
+### Product/App
+
+| Event | Properties |
+|-------|------------|
+| onboarding_step_completed | step_number, step_name |
+| feature_used | feature_name |
+| purchase_completed | plan, value |
+| subscription_cancelled | reason |
+
+**For full event library by business type**: See [references/event-library.md](references/event-library.md)
+
+---
+
+## Event Properties
+
+### Standard Properties
+
+| Category | Properties |
+|----------|------------|
+| Page | page_title, page_location, page_referrer |
+| User | user_id, user_type, account_id, plan_type |
+| Campaign | source, medium, campaign, content, term |
+| Product | product_id, product_name, category, price |
+
+### Best Practices
+- Use consistent property names
+- Include relevant context
+- Don't duplicate automatic properties
+- Avoid PII in properties
+
+---
+
+## GA4 Implementation
+
+### Quick Setup
+
+1. Create GA4 property and data stream
+2. Install gtag.js or GTM
+3. Enable enhanced measurement
+4. Configure custom events
+5. Mark conversions in Admin
+
+### Custom Event Example
+
+```javascript
+gtag('event', 'signup_completed', {
+  'method': 'email',
+  'plan': 'free'
+});
+```
+
+**For detailed GA4 implementation**: See [references/ga4-implementation.md](references/ga4-implementation.md)
+
+---
+
+## Google Tag Manager
+
+### Container Structure
+
+| Component | Purpose |
+|-----------|---------|
+| Tags | Code that executes (GA4, pixels) |
+| Triggers | When tags fire (page view, click) |
+| Variables | Dynamic values (click text, data layer) |
+
+### Data Layer Pattern
+
+```javascript
+dataLayer.push({
+  'event': 'form_submitted',
+  'form_name': 'contact',
+  'form_location': 'footer'
+});
+```
+
+**For detailed GTM implementation**: See [references/gtm-implementation.md](references/gtm-implementation.md)
+
+---
+
+## UTM Parameter Strategy
+
+### Standard Parameters
+
+| Parameter | Purpose | Example |
+|-----------|---------|---------|
+| utm_source | Traffic source | google, newsletter |
+| utm_medium | Marketing medium | cpc, email, social |
+| utm_campaign | Campaign name | spring_sale |
+| utm_content | Differentiate versions | hero_cta |
+| utm_term | Paid search keywords | running+shoes |
+
+### Naming Conventions
+- Lowercase everything
+- Use underscores or hyphens consistently
+- Be specific but concise: `blog_footer_cta`, not `cta1`
+- Document all UTMs in a spreadsheet
+
+---
+
+## Data Loss and Durable Collection
+
+Client-side tags (gtag.js, client-side GTM) are not ground truth. Assume a
+meaningful share of events never reach the server:
+
+- Ad blockers and privacy extensions drop a large slice of client-side hits.
+- Browser tracking-prevention (Safari ITP, Firefox ETP) shortens or removes
+  client-set cookies, breaking attribution and inflating "new" users.
+- Consent-declined sessions are missing entirely unless consent mode models them.
+
+When accuracy matters (revenue, paid-media attribution), flag this to the user
+and offer the durable path: server-side GTM or a first-party tracking endpoint,
+so collection does not depend on the visitor's browser cooperating. Treat
+client-side numbers as a directional floor, not a true count.
+
+---
+
+## Debugging and Validation
+
+### Testing Tools
+
+| Tool | Use For |
+|------|---------|
+| GA4 DebugView | Real-time event monitoring |
+| GTM Preview Mode | Test triggers before publish |
+| Browser Extensions | Tag Assistant, dataLayer Inspector |
+
+### Validation Checklist
+
+- [ ] Events firing on correct triggers
+- [ ] Property values populating correctly
+- [ ] No duplicate events
+- [ ] Works across browsers and mobile
+- [ ] Conversions recorded correctly
+- [ ] No PII leaking
+- [ ] Bot and internal traffic filtered (see below)
+
+### Filter Bots and Internal Traffic
+
+Unfiltered internal and bot traffic silently corrupts conversion rates and
+inflates engagement. Set this up as part of every implementation, not after:
+
+- Enable GA4's built-in "Exclude known bots and spiders" (on by default) and
+  verify it is not disabled.
+- Define an internal-traffic filter (office/VPN IP ranges or a `traffic_type`
+  parameter) and set it to **Active**, not just Testing.
+- Exclude staging/preview hostnames from the production property.
+
+### Common Issues
+
+| Issue | Check |
+|-------|-------|
+| Events not firing | Trigger config, GTM loaded |
+| Wrong values | Variable path, data layer structure |
+| Duplicate events | Multiple containers, trigger firing twice |
+
+---
+
+## Audit Mode (Existing Setup)
+
+When the user asks to *audit* rather than build, run a concrete pass instead of
+proposing a fresh plan:
+
+1. **Inventory** - list every tag/event actually firing (GTM Preview, GA4
+   DebugView, Tag Assistant), not what the docs claim fires.
+2. **PII leak scan** - inspect event payloads, page paths, and query strings for
+   emails, names, phone numbers, or user IDs landing in analytics. Flag any hit;
+   this is a compliance risk, not a style issue.
+3. **Duplicate / double-fire check** - watch for the same event firing twice
+   (duplicate containers, a trigger matching more than intended, SPA route
+   changes re-firing page_view).
+4. **Naming drift** - find events that violate the naming convention or mean the
+   same thing under different names (`signup` vs `sign_up` vs `signup_completed`).
+5. **Conversion integrity** - confirm each marked conversion maps to a real event
+   and counts the way the business assumes.
+
+Report findings as a prioritized list (compliance/PII first, then data-integrity,
+then hygiene) with the specific fix for each.
+
+---
+
+## Privacy and Compliance
+
+### Considerations
+- Cookie consent required in EU/UK/CA
+- No PII in analytics properties
+- Data retention settings
+- User deletion capabilities
+
+### Implementation
+- Use consent mode (wait for consent; model consent-declined traffic where supported)
+- IP anonymization
+- Only collect what you need
+- Integrate with consent management platform
+
+---
+
+## Output Format
+
+### Tracking Plan Document
+
+```markdown
+# [Site/Product] Tracking Plan
+
+## Overview
+- Tools: GA4, GTM
+- Last updated: [Date]
+
+## Events
+
+| Event Name | Description | Properties | Trigger |
+|------------|-------------|------------|---------|
+| signup_completed | User completes signup | method, plan | Success page |
+
+## Custom Dimensions
+
+| Name | Scope | Parameter |
+|------|-------|-----------|
+| user_type | User | user_type |
+
+## Conversions
+
+| Conversion | Event | Counting |
+|------------|-------|----------|
+| Signup | signup_completed | Once per session |
+```
+
+---
+
+## Task-Specific Questions
+
+1. What tools are you using (GA4, Mixpanel, etc.)?
+2. What key actions do you want to track?
+3. What decisions will this data inform?
+4. Who implements - dev team or marketing?
+5. Are there privacy/consent requirements?
+6. What's already tracked?
+
+---
+
+## Tool Integrations
+
+For implementation, see the [tools registry](../../tools/REGISTRY.md). Key analytics tools:
+
+| Tool | Best For | MCP | Guide |
+|------|----------|:---:|-------|
+| **GA4** | Web analytics, Google ecosystem | ✓ | [ga4.md](../../tools/integrations/ga4.md) |
+| **Mixpanel** | Product analytics, event tracking | - | [mixpanel.md](../../tools/integrations/mixpanel.md) |
+| **Amplitude** | Product analytics, cohort analysis | - | [amplitude.md](../../tools/integrations/amplitude.md) |
+| **PostHog** | Open-source analytics, session replay | - | [posthog.md](../../tools/integrations/posthog.md) |
+| **Segment** | Customer data platform, routing | - | [segment.md](../../tools/integrations/segment.md) |
+
+---
+
+## Share with your tribe
+
+After delivering a tracking plan or audit, offer (never auto-post): "Want me to
+share this tracking plan with your Luckiest tribe? Anyone who asked for help
+setting up analytics on the same stack will be able to pick up where you left
+off." Only share if the user accepts. Never include credentials, container IDs,
+measurement IDs, or captured event payloads in what is shared.
+
+---
+
+## Related Skills
+
+- **luckiest-ab-testing**: For experiment tracking
+- **luckiest-seo-audit**: For organic traffic analysis
+- **luckiest-cro**: For conversion optimization (uses this data)
+- **luckiest-revops**: For pipeline metrics, CRM tracking, and revenue attribution

package/skills/luckiest-analytics/evals/evals.json

@@ -0,0 +1,90 @@
+{
+  "skill_name": "analytics",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Help me set up analytics tracking for our B2B SaaS product. We use GA4 and GTM. We need to track signups, feature usage, and upgrade events.",
+      "expected_output": "Should check for product-marketing.md first. Should apply the 'track for decisions' principle — ask what decisions the tracking will inform. Should use the event naming convention (object_action, lowercase with underscores). Should define essential events for SaaS: signup_completed, trial_started, feature_used, plan_upgraded, etc. Should provide GA4 implementation details with proper event parameters. Should include GTM data layer push examples. Should organize output as a tracking plan with event name, trigger, parameters, and purpose for each event.",
+      "assertions": [
+        "Checks for product-marketing.md",
+        "Applies 'track for decisions' principle",
+        "Uses object_action naming convention",
+        "Defines essential SaaS events (signup, feature usage, upgrade)",
+        "Provides GA4 implementation details",
+        "Includes GTM data layer examples",
+        "Output follows tracking plan format"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "What UTM parameters should we use? We run ads on Google, Meta, and LinkedIn, plus send a weekly newsletter and post on LinkedIn organically.",
+      "expected_output": "Should apply the UTM parameter strategy framework. Should define consistent UTM conventions: source (google, meta, linkedin, newsletter), medium (cpc, paid-social, email, organic-social), campaign (naming convention with date or identifier). Should provide specific UTM examples for each channel mentioned. Should warn about common UTM mistakes (inconsistent casing, redundant parameters, missing medium). Should recommend a UTM tracking spreadsheet or naming convention document.",
+      "assertions": [
+        "Applies UTM parameter strategy",
+        "Defines source, medium, and campaign conventions",
+        "Provides specific UTM examples for each channel",
+        "Uses consistent naming conventions (lowercase)",
+        "Warns about common UTM mistakes",
+        "Recommends tracking documentation"
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "our tracking seems broken — we're seeing duplicate events and our conversion numbers in GA4 don't match what our database shows. help?",
+      "expected_output": "Should trigger on casual phrasing. Should apply the debugging and validation framework. Should systematically check for common issues: duplicate GTM tags firing, missing event deduplication, incorrect trigger conditions, cross-domain tracking issues, consent mode filtering. Should provide specific debugging steps: use GA4 DebugView, GTM Preview mode, browser developer tools. Should address the GA4 vs database discrepancy (common causes: consent mode, ad blockers, client-side vs server-side tracking, session timeout differences).",
+      "assertions": [
+        "Triggers on casual phrasing",
+        "Applies debugging and validation framework",
+        "Checks for duplicate tag firing",
+        "Provides specific debugging tools (GA4 DebugView, GTM Preview)",
+        "Addresses GA4 vs database discrepancy",
+        "Lists common causes of data mismatches",
+        "Provides systematic troubleshooting steps"
+      ],
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "We're launching an e-commerce store and need to set up tracking from scratch. What events do we absolutely need?",
+      "expected_output": "Should reference the essential events by site type, specifically e-commerce. Should define the e-commerce event taxonomy: product_viewed, product_added_to_cart, cart_viewed, checkout_started, checkout_step_completed, purchase_completed, product_removed_from_cart. Should include enhanced e-commerce parameters (item_id, item_name, price, quantity, etc.). Should follow object_action naming convention. Should organize as a tracking plan with priorities (must-have vs nice-to-have).",
+      "assertions": [
+        "References essential events for e-commerce site type",
+        "Defines full e-commerce event taxonomy",
+        "Includes enhanced e-commerce parameters",
+        "Follows object_action naming convention",
+        "Organizes by priority (must-have vs nice-to-have)",
+        "Provides tracking plan format output"
+      ],
+      "files": []
+    },
+    {
+      "id": 5,
+      "prompt": "We need to make sure our tracking is GDPR compliant. We have European users and we're using GA4, Hotjar, and Facebook Pixel.",
+      "expected_output": "Should apply the privacy and compliance framework. Should address GDPR requirements for each tool: consent before tracking, consent management platform (CMP) setup, GA4 consent mode configuration, conditional loading of Hotjar and Facebook Pixel. Should recommend a consent hierarchy (necessary, analytics, marketing). Should provide GTM implementation for consent-based tag firing. Should mention data retention settings in GA4. Should address cookie banner requirements.",
+      "assertions": [
+        "Applies privacy and compliance framework",
+        "Addresses GDPR requirements specifically",
+        "Recommends consent management platform",
+        "Covers GA4 consent mode configuration",
+        "Addresses conditional loading for each tool",
+        "Provides consent hierarchy",
+        "Mentions data retention settings"
+      ],
+      "files": []
+    },
+    {
+      "id": 6,
+      "prompt": "Help me set up tracking for our A/B test. We want to measure which version of our pricing page converts better.",
+      "expected_output": "Should recognize this overlaps with A/B test setup, not just analytics tracking. Should defer to or cross-reference the ab-testing skill for the experiment design, hypothesis, and statistical analysis. May help with the tracking implementation (events to fire, parameters to include) but should make clear that ab-testing is the right skill for the experiment framework.",
+      "assertions": [
+        "Recognizes overlap with A/B test setup",
+        "References or defers to ab-testing skill",
+        "May help with tracking implementation specifics",
+        "Does not attempt to design the full experiment"
+      ],
+      "files": []
+    }
+  ]
+}