/rudder-code-first-instrumentation

name: rudder-code-first-instrumentation
description: Derives tracking plans from existing codebase types and structures. Use when instrumenting an existing product that wasn't well-instrumented or restructuring existing tracking.
allowed-tools: "Bash(rudder-cli *), Read, Write, Edit"

Code-First Instrumentation

This skill guides instrumentation planning for **existing products** where you derive tracking plans from the codebase's existing types and structures.

When to Use This Skill

| Scenario | Use This Skill? | |----------|-----------------| | Existing product needs instrumentation | Yes | | Codebase has domain types (enums, interfaces) you want to track | Yes | | Restructuring messy existing tracking | Yes | | Building new feature, events not yet defined | No — use `rudder-design-first-instrumentation` | | LLM chat, AI agent or MCP server usage | No — use `rudder-ai-events-setup` (standard AI events via the AI SDKs) |

Why Code-First?

When a product already exists, the code contains valuable type information:

• **Enums** define valid values (billing plans, user roles, feature types)
• **Interfaces** define object shapes (product, user, workspace)
• **Domain models** define relationships and constraints

Deriving tracking plans from code types:

• Eliminates translation/mapping layers
• Ensures warehouse data matches code semantics
• Enables compile-time validation of instrumentation
• Keeps tracking plan in sync with product evolution

> "If I say plan, that cannot mean many things. It's the plan. I have to be specific."

The Code-First Workflow

┌─────────────────────────────────────────────────────────────────────┐
│                    CODE-FIRST INSTRUMENTATION                        │
└─────────────────────────────────────────────────────────────────────┘
         │
         ▼
┌─────────────────┐
│ 1. DISCOVER     │ ← Identify domain types in codebase
│    CODE TYPES   │
└────────┬────────┘
         ▼
┌─────────────────┐
│ 2. MAP TYPES    │ ← Translate code types to tracking plan types
│    TO YAML      │
└────────┬────────┘
         ▼
┌─────────────────┐
│ 3. IDENTIFY     │ ← What user actions should be tracked?
│    EVENTS       │
└────────┬────────┘
         ▼
┌─────────────────┐
│ 4. BUILD        │ ← Create YAML referencing the types
│    TRACKING     │
│    PLAN         │
└────────┬────────┘
         ▼
┌─────────────────┐
│ 5. VERIFY       │ ← TypeScript compilation validates alignment
└────────┬────────┘
         ▼
┌─────────────────┐
│ 6. TEST & APPLY │ ← Verify in dev workspace, apply to prod
└─────────────────┘

Phase 1: Discover Code Types

Scan the codebase for domain types that should flow through to analytics.

What to Look For

| Type Category | Examples | Tracking Plan Equivalent | |---------------|----------|-------------------------| | Enums | `BillingPlan`, `UserRole`, `Region` | Property with enum config | | String unions | `type Status = 'active' \| 'inactive'` | Property with enum config | | Interfaces | `Product`, `Workspace`, `User` | Custom type | | Constants | `PLAN_TYPES`, `REGIONS` | Property enum values |

Discovery Commands

# Find enums in TypeScript codebase
grep -r "enum " --include="*.ts" --include="*.tsx" src/

# Find type unions
grep -r "type.*=" --include="*.ts" src/ | grep "|"

# Find interfaces that might be tracked
grep -r "interface.*{" --include="*.ts" src/types/

Example: RudderStack Web App Types

// Found in src/types/workspace.ts
enum BillingPlan {
  FREE = 'free',
  STARTER = 'starter',
  GROWTH = 'growth',
  ENTERPRISE = 'enterprise',
}

enum Region {
  US = 'us',
  EU = 'eu',
}

// Found in src/types/transformation.ts
type TransformationLanguage = 'javascript' | 'python';

// Found in src/types/audience.ts
enum ConditionGroupType {
  AND = 'and',
  OR = 'or',
  AUDIENCE = 'audience',
}

Phase 2: Map Types to YAML

Translate discovered code types to tracking plan YAML.

Enum to Property

// Code
enum BillingPlan {
  FREE = 'free',
  STARTER = 'starter',
  GROWTH = 'growth',
  ENTERPRISE = 'enterprise',
}

# Tracking plan property
version: "rudder/v1"
kind: "property"
metadata:
  name: "properties"
spec:
  name: "billing_plan"
  type: "string"
  description: "Organization billing plan"
  config:
    enum:
      - "free"        # Exact match to BillingPlan.FREE
      - "starter"     # Exact match to BillingPlan.STARTER
      - "growth"      # Exact match to BillingPlan.GROWTH
      - "enterprise"  # Exact match to BillingPlan.ENTERPRISE

String Union to Property

// Code
type TransformationLanguage = 'javascript' | 'python';

# Tracking plan property
version: "rudder/v1"
kind: "property"
metadata:
  name: "properties"
spec:
  name: "transformation_language"
  type: "string"
  description: "Programming language of transformation"
  config:
    enum:
      - "javascript"
      - "python"

Interface to Custom Type

// Code
interface Product {
  id: string;
  name: string;
  price: number;
  category: ProductCategory;
}

# Tracking plan custom type
version: "rudder/v1"
kind: "custom-type"
metadata:
  name: "custom-types"
spec:
  name: "ProductType"
  type: "object"
  description: "Product information from catalog"
  config:
    properties:
      - property: "urn:rudder:property/product_id"
        required: true
      - property: "urn:rudder:property/product_name"
        required: true
      - property: "urn:rudder:property/product_price"
        required: true
      - property: "urn:rudder:property/product_category"
        required: true

Critical: Use Exact Values

The tracking plan **must** use the exact string values from the code:

// If code uses lowercase
enum Region {
  US = 'us',    // lowercase
  EU = 'eu',
}

// YAML must match
config:
  enum:
    - "us"      # NOT "US"
    - "eu"      # NOT "EU"

Phase 3: Identify Events

Wi