/rudder-tracking-plans

name: rudder-tracking-plans
description: Creates and manages tracking plans that validate events against schema contracts. Use when creating or managing tracking plans that define which events are allowed for a source
allowed-tools: "Bash(rudder-cli *), Read, Write, Edit"

RudderStack Tracking Plans Management

This skill teaches how to assemble events into **tracking plans** - contracts that define which events a source can send and what properties each event must have.

What is a Tracking Plan?

A tracking plan is a schema that:

• Defines **which events** are allowed from a source
• Specifies **required vs optional properties** for each event
• Enables **validation** at event ingestion time
• Provides **governance** over what data enters your warehouse

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│     Source      │────▶│  Tracking Plan  │────▶│   Destination   │
│  (Web App SDK)  │     │   (Validator)   │     │   (Warehouse)   │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                               │
                        Validates events
                        against schema

YAML Schema

Basic Tracking Plan

version: "rudder/v1"
kind: "tracking-plan"
metadata:
  name: "tracking-plans"
spec:
  name: "Web App Tracking Plan"
  description: "Events for the main e-commerce web application"
  events:
    - event: "urn:rudder:event/product-viewed"
    - event: "urn:rudder:event/product-added-to-cart"
    - event: "urn:rudder:event/order-completed"

Tracking Plan with Rule Overrides

Override event-level rules at the tracking plan level:

version: "rudder/v1"
kind: "tracking-plan"
metadata:
  name: "tracking-plans"
spec:
  name: "Mobile App Tracking Plan"
  description: "Events for iOS and Android apps"
  events:
    - event: "urn:rudder:event/product-viewed"
      rules:
        # Make session_id required for mobile (optional in event definition)
        - property: "urn:rudder:property/session_id"
          required: true
        # Make device_id required for mobile attribution
        - property: "urn:rudder:property/device_id"
          required: true
    - event: "urn:rudder:event/product-added-to-cart"
    - event: "urn:rudder:event/order-completed"

Rule Precedence

When the same property appears at multiple levels:

1. Tracking Plan event rules  (highest priority)
2. Event-level rules          (default)
3. Property definitions       (validation config only)

**Example:** If `session_id` is optional in the event definition but required in the tracking plan, it's **required** for that tracking plan.

Real-World Example

See `references/ecommerce-example.md` for a complete e-commerce example showing:

• Shared event catalog used by web, mobile, and kiosk apps
• Web App tracking plan (full funnel with page attribution)
• Mobile App tracking plan (device_id attribution)
• Kiosk tracking plan (limited event set)
• Environment-specific plans (production vs development)
• Gradual rollout patterns

Governance Settings

When events violate the tracking plan:

spec:
  name: "Strict Tracking Plan"
  governance:
    # Options: block, forward, log
    unplannedEvents: block      # Reject events not in plan
    violatingEvents: forward    # Forward violations with flag

| Setting | Behavior | |---------|----------| | `block` | Reject event entirely | | `forward` | Forward event with violation metadata | | `log` | Allow event, log violation for review |

Directory Structure

tracking-plans/
├── web-app.yaml
├── mobile-app.yaml
├── kiosk.yaml
└── internal-tools.yaml

Each tracking plan in its own file for clear git history and code review.

Workflow: Creating a New Tracking Plan

Step 1: Identify the Source

What application/SDK will use this tracking plan?

• Web app (JavaScript SDK)
• Mobile app (iOS/Android SDK)
• Server-side (Node.js SDK)

Step 2: List Required Events

Which events from your data catalog does this source need?

Web App needs:
✓ Product Viewed
✓ Product Added to Cart
✓ Order Completed
✗ App Opened (mobile only)

Step 3: Determine Rule Overrides

For each event, what properties should be:

• **Required** for this source specifically?
• **Optional** even if required elsewhere?

Step 4: Create the YAML

version: "rudder/v1"
kind: "tracking-plan"
metadata:
  name: "tracking-plans"
spec:
  name: "Your Tracking Plan Name"
  description: "Clear description of what source uses this"
  events:
    - event: "urn:rudder:event/event-name"
      rules:
        - property: "urn:rudder:property/property-name"
          required: true

Step 5: Validate and Apply

# Validate
rudder-cli validate -l ./

# Preview
rudder-cli apply --dry-run -l ./

# Apply
rudder-cli apply -l ./

Step 6: Connect to Source

After applying, connect the tracking plan to your source:

• Via RudderStack UI: Sources → Select Source → Tracking Plan
• Via API: Update source configuration

Common Patterns

Pattern: Environment-Specific Plans

# tracking-plans/web-app-production.yaml
spec:
  name: "Web App - Production"
  governance:
    unplannedEvents: block      # Strict in production
    violatingEvents: block

# tracking-plans/web-app-development.yaml
spec:
  name: "Web App - Development"
  governance:
    unplannedEvents: log        # Lenient in development
    violatingEvents: forward

Pattern: Shared Base + Overrides

Create a comprehensive event catalog, then each tracking plan includes only what it needs:

Data Catalog: 50 events defined
├── Web App Plan: 30 events
├── Mobile Plan: 25 events
└── Kiosk Plan: 5 events

Pattern: Gradual Rollout

Start permissive, tighten over time:

# Phase 1: Log only
governance:
  unplannedEvents: log
  violatingEvents: log

# Phase 2: Forward violations
governance:
  unplannedEvents: forward
  violatingEvents: forward

# Phase 3: Block vio