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

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

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

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