/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` | | LLM chat, AI agent or MCP server usage | No — use `rudder-ai-events-setup` (standard AI events via the AI SDKs) |

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 appr