/rudder-instrumentation-planning

name: rudder-instrumentation-planning
description: Designs event taxonomies and instrumentation strategies from business requirements. Use when designing event taxonomy from scratch or restructuring existing instrumentation strategy
allowed-tools: "Bash(rudder-cli *), Read, Write, Edit"

Instrumentation Planning

This skill guides you through designing an **instrumentation strategy** - the systematic approach to deciding what events and properties to track in your application.

Why Planning Matters

Poor instrumentation leads to:

• **Data gaps** - Can't answer business questions
• **Data bloat** - Too many events, high costs, noise
• **Inconsistency** - Same action tracked differently across teams
• **Technical debt** - Constant schema changes breaking dashboards

Good instrumentation provides:

• **Complete funnel visibility** - Every step from acquisition to retention
• **Consistent naming** - Clear conventions everyone follows
• **Maintainable schema** - Easy to extend, hard to break
• **Actionable insights** - Data that drives decisions

Choose Your Workflow

Different starting points require different approaches:

| Your Situation | Recommended Skill | |----------------|-------------------| | Building new feature, events not yet defined | `rudder-design-first-instrumentation` | | Existing product needs instrumentation | `rudder-code-first-instrumentation` | | Restructuring existing tracking | `rudder-code-first-instrumentation` | | General planning guidance | Continue with this skill |

Design-First vs Code-First

**Design-First:** Start from product requirements → define events → define properties → implement code. Best for new features where events are part of product definition.

**Code-First:** Start from existing code types → derive tracking plan → align with data governance. Best for existing products with domain types already defined.

This skill covers the general planning process. For workflow-specific guidance, see the specialized skills above.

The Planning Process

┌─────────────────────────────────────────────────────────────────────┐
│                     INSTRUMENTATION PLANNING                         │
└─────────────────────────────────────────────────────────────────────┘
         │
         ▼
┌─────────────────┐
│ 1. DISCOVERY    │ ← What questions do we need to answer?
└────────┬────────┘
         ▼
┌─────────────────┐
│ 2. TAXONOMY     │ ← What events and properties will answer them?
└────────┬────────┘
         ▼
┌─────────────────┐
│ 3. BUILD        │ ← Create the YAML definitions
└────────┬────────┘
         ▼
┌─────────────────┐
│ 4. ASSEMBLE     │ ← Group into tracking plans
└────────┬────────┘
         ▼
┌─────────────────┐
│ 5. INTEGRATE    │ ← Generate code, implement in apps
└─────────────────┘

Phase 1: Discovery

Questions to Ask Stakeholders

**Business Questions:**

• What KPIs do we track? (conversion rate, retention, revenue)
• What funnels do we analyze? (signup, checkout, onboarding)
• What experiments will we run? (A/B tests need specific events)
• What attribution do we need? (marketing channels, campaigns)

**Product Questions:**

• What are the key user journeys?
• What features do we want to measure adoption for?
• What errors/failures do we need to monitor?

**Technical Questions:**

• What platforms exist? (web, iOS, Android, server)
• What existing tracking is in place?
• What tools consume this data? (Amplitude, Mixpanel, warehouse)

Discovery Template

## Business Goals
- [ ] Primary KPIs: _______________
- [ ] Key funnels: _______________
- [ ] Attribution needs: _______________

## User Journeys to Track
1. _______________
2. _______________
3. _______________

## Platforms
- [ ] Web
- [ ] iOS
- [ ] Android
- [ ] Server

## Existing Tracking
- Current events: ___ events
- Issues with current: _______________

Phase 2: Taxonomy Design

Step 1: Define Event Categories

Group events by business domain:

| Category | Purpose | Examples | |----------|---------|----------| | `user-lifecycle` | Account actions | Signed Up, Logged In, Profile Updated | | `ecommerce` | Purchase funnel | Product Viewed, Added to Cart, Order Completed | | `engagement` | Feature usage | Feature Used, Content Viewed, Search Performed | | `errors` | Failure tracking | Error Occurred, Checkout Failed |

Step 2: Map User Journeys to Events

**Example: E-Commerce Funnel**

User Journey                    Events
───────────                    ──────
Browse products         →      Product Viewed
Add to cart            →      Product Added to Cart
Start checkout         →      Checkout Started
Complete purchase      →      Order Completed

**Example: SaaS Onboarding**

User Journey                    Events
───────────                    ──────
Create account         →      Signed Up
Verify email           →      Email Verified
Complete profile       →      Profile Completed
Use first feature      →      Feature Used (first_time: true)
Invite teammate        →      Team Member Invited

Step 3: Identify Properties

For each event, list required context:

**Product Viewed**

• Required: product_id, product_name, product_price, product_category
• Optional: page_url, referrer_url, session_id
• Context: How did they find it? What were they looking at?

**Order Completed**

• Required: order_id, order_total, products, customer_email
• Optional: discount_code, shipping_method, payment_method
• Context: What did they buy? How much? What discounts?

Step 4: Identify Shared Patterns

Look for properties used across multiple events:

Shared across all events:
- session_id
- user_id (if logged in)
- timestamp (automatic)

Shared across e-commerce events:
- product object (id, name, price, category)

Shared across Order Completed:
- address object (street, city, state, zip)

These become **Custom Types**.

Phase 3: Build the Data Catalog

Order of Creation

1. Custom Types    ←