rudder-design-first-instrumentation

name	rudder-design-first-instrumentation
description	Plans instrumentation for new features starting from product requirements before code exists. Use when building new features and need to define events as part of product definition.
allowed-tools	Bash(rudder-cli *), Read, Write, Edit

Design-First Instrumentation

This skill guides instrumentation planning for new features where events are defined during product definition, before implementation begins.

When to Use This Skill

Scenario	Use This Skill?
Building a new feature, events not yet defined	Yes
Product requirements include analytics needs	Yes
PM and engineering collaborating on what to track	Yes
Existing product needs instrumentation	No — use rudder-code-first-instrumentation
Restructuring existing tracking	No — use rudder-code-first-instrumentation

The Design-First Workflow

┌─────────────────────────────────────────────────────────────────────┐
│                    DESIGN-FIRST INSTRUMENTATION                      │
└─────────────────────────────────────────────────────────────────────┘
         │
         ▼
┌─────────────────┐
│ 1. REQUIREMENTS │ ← What questions must the data answer?
└────────┬────────┘
         ▼
┌─────────────────┐
│ 2. EVENT DESIGN │ ← Define events (names only, no properties yet)
└────────┬────────┘
         ▼
┌─────────────────┐
│ 3. HUMAN        │ ← PM/Eng review: Are these the right events?
│    CHECKPOINT   │
└────────┬────────┘
         ▼
┌─────────────────┐
│ 4. PROPERTY     │ ← Define properties for approved events
│    DESIGN       │
└────────┬────────┘
         ▼
┌─────────────────┐
│ 5. BUILD YAML   │ ← Create tracking plan definitions
└────────┬────────┘
         ▼
┌─────────────────┐
│ 6. IMPLEMENT    │ ← Code the feature with instrumentation
└─────────────────┘

Phase 1: Requirements Gathering

Start with the questions the data must answer:

Questions Template

## Feature: [Feature Name]

### Business Questions
- [ ] What is the conversion rate through this feature?
- [ ] Where do users drop off?
- [ ] How long does it take users to complete the flow?
- [ ] What variations do users prefer?

### Success Metrics
- Primary: _______________
- Secondary: _______________

### Funnel Stages
1. Entry point: _______________
2. Key action: _______________
3. Completion: _______________

### Stakeholders
- PM: _______________
- Engineering: _______________
- Data/Analytics: _______________

Phase 2: Event Design (Names Only)

Define events as user stories or behavioral descriptions first — no properties yet.

Event Description Format

Use clear, behavioral language:

## Events for [Feature Name]

### Event: Feature Opened
- **When:** User opens the feature for the first time in a session
- **Why track:** Measures feature discovery and initial engagement
- **Funnel position:** Entry

### Event: Configuration Started
- **When:** User begins configuring the feature
- **Why track:** Measures intent to use feature
- **Funnel position:** Middle

### Event: Configuration Completed
- **When:** User successfully completes configuration
- **Why track:** Measures successful adoption
- **Funnel position:** Completion

### Event: Configuration Failed
- **When:** User encounters an error during configuration
- **Why track:** Identifies friction points
- **Funnel position:** Error state

Naming Convention

Pattern	Example	Use For
Feature + Action (Past Tense)	Audience Created	Completed actions
Feature + State	Checkout Started	State transitions
Object + Action	Product Viewed	Standard interactions

Phase 3: Human Checkpoint

Critical: Before defining properties, get alignment on events.

Review Checklist

• Do these events answer all the business questions?
• Is the funnel complete (entry → middle → completion)?
• Are error states captured?
• Are there redundant events that can be consolidated?
• Do event names follow conventions?

Approval Gate

## Event Review Sign-Off

Feature: _______________
Date: _______________

Approved Events:
- [ ] Event 1: _______________
- [ ] Event 2: _______________
- [ ] Event 3: _______________

Rejected/Deferred:
- [ ] _______________

Approved by:
- PM: _______________
- Engineering: _______________

Phase 4: Property Design

After events are approved, define properties for each.

Property Design Process

For each event, ask:

1. What context is needed to answer the business questions?
2. What attributes describe this action?
3. What will we group/filter by in dashboards?

Property Template

## Event: Audience Created

### Required Properties
| Property | Type | Description | Example |
|----------|------|-------------|---------|
| audience_id | string | Unique identifier | "aud_123" |
| audience_name | string | User-provided name | "High Value Users" |
| condition_count | integer | Number of conditions | 3 |

### Optional Properties
| Property | Type | Description | Example |
|----------|------|-------------|---------|
| template_used | string | If created from template | "ecommerce-buyers" |
| creation_method | string | How it was created | "wizard" \| "manual" |

### Context (Auto-included)
- workspace_id (from session context)
- user_id (from identify)

Identify Shared Patterns

Look for properties used across multiple events — these become custom types:

## Shared Patterns Identified

### AudienceType (used by: Created, Updated, Deleted)
- audience_id
- audience_name
- audience_type

### ConditionType (used by: Created, Updated)
- condition_id
- condition_type
- condition_operator

Phase 5: Build YAML Definitions

Convert approved designs to tracking plan YAML.

Order of Creation

1. Custom Types    ← Reusable patterns identified in Phase 4
2. Properties      ← Individual property definitions
3. Categories      ← Organize events by feature/domain
4. Events          ← Reference properties and custom types
5. Tracking Plan   ← Bundle events for the source

Example: Custom Type

version: "rudder/v1"
kind: "custom-type"
metadata:
  name: "custom-types"
spec:
  name: "AudienceType"
  type: "object"
  description: "Core audience information"
  config:
    properties:
      - property: "urn:rudder:property/audience_id"
        required: true
      - property: "urn:rudder:property/audience_name"
        required: true
      - property: "urn:rudder:property/audience_type"
        required: true

Example: Event

version: "rudder/v1"
kind: "event"
metadata:
  name: "events"
spec:
  name: "Audience Created"
  description: "User successfully created a new audience"
  category: "urn:rudder:category/audiences"
  rules:
    - property: "urn:rudder:property/audience"
      required: true
      customType: "urn:rudder:custom-type/audience-type"
    - property: "urn:rudder:property/condition_count"
      required: true
    - property: "urn:rudder:property/template_used"
    - property: "urn:rudder:property/creation_method"

Validate and Apply

# Validate definitions
rudder-cli validate -l ./

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

# Apply to workspace
rudder-cli apply -l ./

Phase 6: Implementation

With tracking plan applied, implement the feature with instrumentation.

Implementation Checklist

• Tracking plan applied to workspace
• Events documented for developers
• Instrumentation added at correct points in code
• Context middleware configured (workspace_id)
• Tested in dev environment
• Verified events reach destination

Code Pattern

// Feature implementation with instrumentation
async function createAudience(config: AudienceConfig): Promise<Audience> {
  const audience = await audienceService.create(config);

  // Instrumentation
  analytics.track('Audience Created', {
    audience_id: audience.id,
    audience_name: audience.name,
    audience_type: audience.type,
    condition_count: config.conditions.length,
    template_used: config.templateId || null,
    creation_method: config.method,
  });

  return audience;
}

Collaboration Patterns

PM-Led Event Design

PM writes event descriptions (Phase 2)
    ↓
Engineering reviews for feasibility
    ↓
Joint checkpoint (Phase 3)
    ↓
Engineering leads property design (Phase 4)
    ↓
PM validates properties answer questions
    ↓
Engineering implements

Engineering-Led with PM Input

Engineering drafts events based on feature spec
    ↓
PM reviews for analytics completeness
    ↓
Joint refinement
    ↓
Engineering completes properties + implementation

Real-World Examples

For complete end-to-end examples including RudderStack Audiences and Transformations features, see references/real-world-examples.md.

---

Common Mistakes

Mistake	Problem	Fix
Skipping human checkpoint	Events don't answer business questions	Always get sign-off before properties
Properties before events	Scope creep, over-instrumentation	Define event names first, properties second
Too granular events	Data bloat, high costs	Use properties for variations, not separate events
Missing error states	Can't diagnose failures	Always include failure/error events
No shared patterns	Duplicate properties, inconsistency	Identify custom types early
Enum values don't match code	Type mismatches, glue code needed	Check existing code types before defining properties

Checklist

Before implementation:

• Business questions documented
• Events designed with behavioral descriptions
• Human checkpoint completed (events approved)
• Properties designed for each event
• Shared patterns extracted as custom types
• YAML definitions created
• rudder-cli validate passes
• Tracking plan applied to dev workspace
• Implementation plan includes instrumentation points