/suede-analytics

name: suede-analytics
description: "Suede AI measurement discipline: tracking plans, event and key-event instrumentation in GA4 and GTM, consent mode v2, UTM hygiene, AI assistant and organic search channel grouping, and readback proof of what actually fires. Use when setting up, auditing, or repairing analytics across web, product, paid, and lifecycle surfaces. NOT FOR: experiment design or significance (use suede-ab-testing), campaign optimization (use suede-ads), attribution models, model comparison, or cross-tool reconciliation (use suede-attribution), or revenue-process architecture (use suede-revops)."
metadata:
  version: 2.1.0

Suede AI Analytics Tracking

Use this measurement playbook to build tracking that supports auditable marketing and product decisions.

Initial Assessment

Check for `.agents/product-marketing.md` (or `.claude/product-marketing.md`, or the legacy `product-marketing-context.md`) and read it if present: the key conversions, the decisions the data has to serve, and the tools already in place drive every recommendation here.

Then work the intake list under Task-Specific Questions below; ask only what the context file did not already answer.

---

Production Changes: Halt Before Mutating

Editing live tags, properties, destinations, or consent settings is the highest-consequence action in this skill, and Boundaries below forbids doing it without explicit authorization and a rollback plan. When a task requires one and you do not have both, halt in four parts:

1. Stop. Do not publish the container, edit the property, or change the consent configuration. 2. Name the blocker in one line ("publishing this GTM container version changes what fires for all live traffic; I have no rollback version identified"). 3. Offer 2-4 options (stage it in Preview and hand over the trace; write the change as a diff for the owner to publish; publish after the user names the rollback version; scope the change to a test environment). 4. Wait for the answer. Do not pick one and continue.

The same halt applies to anything the Privacy and Compliance section below sends to legal or privacy review: an unresolved lawful-basis question blocks implementation, it does not get an assumption.

---

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

---

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

• Avoid PII in properties
• Reuse the Standard Properties names above rather than inventing per-event variants

---

GA4 Implementation

Quick Setup

1. Create GA4 property and data stream 2. Install the Google tag (gtag.js) or GTM, with consent mode v2 defaults set before any tag fires 3. Enable enhanced measurement 4. Configure custom events 5. Mark key events in Admin (GA4 renamed "conversions" to key events in March 2024), then create Google Ads conversions from the key events that bidding should use

Custom Event Example

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

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

---

Search and AI Assistant Traffic

Organic search and AI answer engines now send tr