arkaos 4.26.0 → 4.28.0

package/departments/marketing/skills/analytics-report/SKILL.md

@@ -12,6 +12,10 @@ description: >
   content/analytics; funnel step conversion diagnosis ->
   landing/funnel-metrics.
 allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
+metadata:
+  origin: community
+  source: https://github.com/coreyhaines31/marketingskills
+  license: MIT
 ---
 
 <!-- arka:kb-first-prefix begin -->
@@ -25,9 +29,314 @@ allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 
 > **Agent:** Luna (Marketing Director) | **Framework:** AARRR Pirate Metrics
 
+**Context:** read the product marketing context first —
+`WizardingCode/Marketing/product-marketing.md` in Obsidian (KB-first),
+else the project-local `.agents/product-marketing.md`.
+
 ## What It Does
 
-Marketing analytics report: AARRR funnel, channel performance, CAC trends.
+Produces the marketing analytics report — the AARRR pirate-metrics funnel,
+channel performance breakdown, and CAC trends — and sets up the tracking
+that feeds it. A report is only as honest as its instrumentation, so this
+skill covers both the measurement plan (events, GA4, GTM, UTMs) and the
+reporting layer on top. The goal is tracking that provides actionable
+insights for marketing and product decisions.
+
+## Initial Assessment
+
+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 the full event library**: 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 the 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
+
+---
+
+## 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
+
+### 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 |
+
+---
+
+## 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)
+- 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) |
+
+---
+
+## Related ArkaOS skills
+
+- **`landing/ab-test`** — experiment tracking and measurement
+- **`mkt/seo-audit`** — organic traffic analysis
+- **`landing/optimize-page`** — conversion optimization (uses this data)
+- **`sales/revops`** — pipeline metrics, CRM tracking, and revenue attribution
 
 ## Output
 

package/departments/marketing/skills/analytics-report/references/event-library.md

@@ -0,0 +1,260 @@
+# Event Library Reference
+
+Comprehensive list of events to track by business type and context.
+
+## Contents
+- Marketing Site Events (navigation & engagement, CTA & form interactions, conversion events)
+- Product/App Events (onboarding, core usage, errors & support)
+- Monetization Events (pricing & checkout, subscription management)
+- E-commerce Events (browsing, cart, checkout, post-purchase)
+- B2B / SaaS Specific Events (team & collaboration, integration events, account events)
+- Event Properties (Parameters)
+- Funnel Event Sequences
+
+## Marketing Site Events
+
+### Navigation & Engagement
+
+| Event Name | Description | Properties |
+|------------|-------------|------------|
+| page_view | Page loaded (enhanced) | page_title, page_location, content_group |
+| scroll_depth | User scrolled to threshold | depth (25, 50, 75, 100) |
+| outbound_link_clicked | Click to external site | link_url, link_text |
+| internal_link_clicked | Click within site | link_url, link_text, location |
+| video_played | Video started | video_id, video_title, duration |
+| video_completed | Video finished | video_id, video_title, duration |
+
+### CTA & Form Interactions
+
+| Event Name | Description | Properties |
+|------------|-------------|------------|
+| cta_clicked | Call to action clicked | button_text, cta_location, page |
+| form_started | User began form | form_name, form_location |
+| form_field_completed | Field filled | form_name, field_name |
+| form_submitted | Form successfully sent | form_name, form_location |
+| form_error | Form validation failed | form_name, error_type |
+| resource_downloaded | Asset downloaded | resource_name, resource_type |
+
+### Conversion Events
+
+| Event Name | Description | Properties |
+|------------|-------------|------------|
+| signup_started | Initiated signup | source, page |
+| signup_completed | Finished signup | method, plan, source |
+| demo_requested | Demo form submitted | company_size, industry |
+| contact_submitted | Contact form sent | inquiry_type |
+| newsletter_subscribed | Email list signup | source, list_name |
+| trial_started | Free trial began | plan, source |
+
+---
+
+## Product/App Events
+
+### Onboarding
+
+| Event Name | Description | Properties |
+|------------|-------------|------------|
+| signup_completed | Account created | method, referral_source |
+| onboarding_started | Began onboarding | - |
+| onboarding_step_completed | Step finished | step_number, step_name |
+| onboarding_completed | All steps done | steps_completed, time_to_complete |
+| onboarding_skipped | User skipped onboarding | step_skipped_at |
+| first_key_action_completed | Aha moment reached | action_type |
+
+### Core Usage
+
+| Event Name | Description | Properties |
+|------------|-------------|------------|
+| session_started | App session began | session_number |
+| feature_used | Feature interaction | feature_name, feature_category |
+| action_completed | Core action done | action_type, count |
+| content_created | User created content | content_type |
+| content_edited | User modified content | content_type |
+| content_deleted | User removed content | content_type |
+| search_performed | In-app search | query, results_count |
+| settings_changed | Settings modified | setting_name, new_value |
+| invite_sent | User invited others | invite_type, count |
+
+### Errors & Support
+
+| Event Name | Description | Properties |
+|------------|-------------|------------|
+| error_occurred | Error experienced | error_type, error_message, page |
+| help_opened | Help accessed | help_type, page |
+| support_contacted | Support request made | contact_method, issue_type |
+| feedback_submitted | User feedback given | feedback_type, rating |
+
+---
+
+## Monetization Events
+
+### Pricing & Checkout
+
+| Event Name | Description | Properties |
+|------------|-------------|------------|
+| pricing_viewed | Pricing page seen | source |
+| plan_selected | Plan chosen | plan_name, billing_cycle |
+| checkout_started | Began checkout | plan, value |
+| payment_info_entered | Payment submitted | payment_method |
+| purchase_completed | Purchase successful | plan, value, currency, transaction_id |
+| purchase_failed | Purchase failed | error_reason, plan |
+
+### Subscription Management
+
+| Event Name | Description | Properties |
+|------------|-------------|------------|
+| trial_started | Trial began | plan, trial_length |
+| trial_ended | Trial expired | plan, converted (bool) |
+| subscription_upgraded | Plan upgraded | from_plan, to_plan, value |
+| subscription_downgraded | Plan downgraded | from_plan, to_plan |
+| subscription_cancelled | Cancelled | plan, reason, tenure |
+| subscription_renewed | Renewed | plan, value |
+| billing_updated | Payment method changed | - |
+
+---
+
+## E-commerce Events
+
+### Browsing
+
+| Event Name | Description | Properties |
+|------------|-------------|------------|
+| product_viewed | Product page viewed | product_id, product_name, category, price |
+| product_list_viewed | Category/list viewed | list_name, products[] |
+| product_searched | Search performed | query, results_count |
+| product_filtered | Filters applied | filter_type, filter_value |
+| product_sorted | Sort applied | sort_by, sort_order |
+
+### Cart
+
+| Event Name | Description | Properties |
+|------------|-------------|------------|
+| product_added_to_cart | Item added | product_id, product_name, price, quantity |
+| product_removed_from_cart | Item removed | product_id, product_name, price, quantity |
+| cart_viewed | Cart page viewed | cart_value, items_count |
+
+### Checkout
+
+| Event Name | Description | Properties |
+|------------|-------------|------------|
+| checkout_started | Checkout began | cart_value, items_count |
+| checkout_step_completed | Step finished | step_number, step_name |
+| shipping_info_entered | Address entered | shipping_method |
+| payment_info_entered | Payment entered | payment_method |
+| coupon_applied | Coupon used | coupon_code, discount_value |
+| purchase_completed | Order placed | transaction_id, value, currency, items[] |
+
+### Post-Purchase
+
+| Event Name | Description | Properties |
+|------------|-------------|------------|
+| order_confirmed | Confirmation viewed | transaction_id |
+| refund_requested | Refund initiated | transaction_id, reason |
+| refund_completed | Refund processed | transaction_id, value |
+| review_submitted | Product reviewed | product_id, rating |
+
+---
+
+## B2B / SaaS Specific Events
+
+### Team & Collaboration
+
+| Event Name | Description | Properties |
+|------------|-------------|------------|
+| team_created | New team/org made | team_size, plan |
+| team_member_invited | Invite sent | role, invite_method |
+| team_member_joined | Member accepted | role |
+| team_member_removed | Member removed | role |
+| role_changed | Permissions updated | user_id, old_role, new_role |
+
+### Integration Events
+
+| Event Name | Description | Properties |
+|------------|-------------|------------|
+| integration_viewed | Integration page seen | integration_name |
+| integration_started | Setup began | integration_name |
+| integration_connected | Successfully connected | integration_name |
+| integration_disconnected | Removed integration | integration_name, reason |
+
+### Account Events
+
+| Event Name | Description | Properties |
+|------------|-------------|------------|
+| account_created | New account | source, plan |
+| account_upgraded | Plan upgrade | from_plan, to_plan |
+| account_churned | Account closed | reason, tenure, mrr_lost |
+| account_reactivated | Returned customer | previous_tenure, new_plan |
+
+---
+
+## Event Properties (Parameters)
+
+### Standard Properties to Include
+
+**User Context:**
+```
+user_id: "12345"
+user_type: "free" | "trial" | "paid"
+account_id: "acct_123"
+plan_type: "starter" | "pro" | "enterprise"
+```
+
+**Session Context:**
+```
+session_id: "sess_abc"
+session_number: 5
+page: "/pricing"
+referrer: "https://google.com"
+```
+
+**Campaign Context:**
+```
+source: "google"
+medium: "cpc"
+campaign: "spring_sale"
+content: "hero_cta"
+```
+
+**Product Context (E-commerce):**
+```
+product_id: "SKU123"
+product_name: "Product Name"
+category: "Category"
+price: 99.99
+quantity: 1
+currency: "USD"
+```
+
+**Timing:**
+```
+timestamp: "2024-01-15T10:30:00Z"
+time_on_page: 45
+session_duration: 300
+```
+
+---
+
+## Funnel Event Sequences
+
+### Signup Funnel
+1. signup_started
+2. signup_step_completed (email)
+3. signup_step_completed (password)
+4. signup_completed
+5. onboarding_started
+
+### Purchase Funnel
+1. pricing_viewed
+2. plan_selected
+3. checkout_started
+4. payment_info_entered
+5. purchase_completed
+
+### E-commerce Funnel
+1. product_viewed
+2. product_added_to_cart
+3. cart_viewed
+4. checkout_started
+5. shipping_info_entered
+6. payment_info_entered
+7. purchase_completed