rudder-code-first-instrumentation

Name: rudder-code-first-instrumentation
Author: rudderlabs

18stars0forks

How to install rudder-code-first-instrumentation?

rudderlabs/rudder-agent-skills/rudder-code-first-instrumentation

$npx -y skills add rudderlabs/rudder-agent-skills --skill rudder-code-first-instrumentation

Installs into the current project.

Summary

Derives tracking plans from existing codebase types and structures. Use when instrumenting an existing product that wasn't well-instrumented or restructuring existing tracking.

Files · 1

View on GitHub

SKILL.md

1	# Code-First Instrumentation
2
3	This skill guides instrumentation planning for existing products where you derive tracking plans from the codebase's existing types and structures.
4
5	## When to Use This Skill
6
7	\| Scenario \| Use This Skill? \|
8	\|----------\|-----------------\|
9	\| Existing product needs instrumentation \| Yes \|
10	\| Codebase has domain types (enums, interfaces) you want to track \| Yes \|
11	\| Restructuring messy existing tracking \| Yes \|
12	\| Building new feature, events not yet defined \| No — use `rudder-design-first-instrumentation` \|
13
14	## Why Code-First?
15
16	When a product already exists, the code contains valuable type information:
17
18	- Enums define valid values (billing plans, user roles, feature types)
19	- Interfaces define object shapes (product, user, workspace)
20	- Domain models define relationships and constraints
21
22	Deriving tracking plans from code types:
23	- Eliminates translation/mapping layers
24	- Ensures warehouse data matches code semantics
25	- Enables compile-time validation of instrumentation
26	- Keeps tracking plan in sync with product evolution
27
28	> "If I say plan, that cannot mean many things. It's the plan. I have to be specific."
29
30	## The Code-First Workflow
31
32	```
33	┌─────────────────────────────────────────────────────────────────────┐
34	│ CODE-FIRST INSTRUMENTATION │
35	└─────────────────────────────────────────────────────────────────────┘
36	│
37	▼
38	┌─────────────────┐
39	│ 1. DISCOVER │ ← Identify domain types in codebase
40	│ CODE TYPES │
41	└────────┬────────┘
42	▼
43	┌─────────────────┐
44	│ 2. MAP TYPES │ ← Translate code types to tracking plan types
45	│ TO YAML │
46	└────────┬────────┘
47	▼
48	┌─────────────────┐
49	│ 3. IDENTIFY │ ← What user actions should be tracked?
50	│ EVENTS │
51	└────────┬────────┘
52	▼
53	┌─────────────────┐
54	│ 4. BUILD │ ← Create YAML referencing the types
55	│ TRACKING │
56	│ PLAN │
57	└────────┬────────┘
58	▼
59	┌─────────────────┐
60	│ 5. VERIFY │ ← TypeScript compilation validates alignment
61	└────────┬────────┘
62	▼
63	┌─────────────────┐
64	│ 6. TEST & APPLY │ ← Verify in dev workspace, apply to prod
65	└─────────────────┘
66	```
67
68	## Phase 1: Discover Code Types
69
70	Scan the codebase for domain types that should flow through to analytics.
71
72	### What to Look For
73
74	\| Type Category \| Examples \| Tracking Plan Equivalent \|
75	\|---------------\|----------\|-------------------------\|
76	\| Enums \| `BillingPlan`, `UserRole`, `Region` \| Property with enum config \|
77	\| String unions \| `type Status = 'active' \\| 'inactive'` \| Property with enum config \|
78	\| Interfaces \| `Product`, `Workspace`, `User` \| Custom type \|
79	\| Constants \| `PLAN_TYPES`, `REGIONS` \| Property enum values \|
80
81	### Discovery Commands
82
83	```bash
84	# Find enums in TypeScript codebase
85	grep -r "enum " --include=".ts" --include=".tsx" src/
86
87	# Find type unions
88	grep -r "type.=" --include=".ts" src/ \| grep "\|"
89
90	# Find interfaces that might be tracked
91	grep -r "interface.{" --include=".ts" src/types/
92	```
93
94	### Example: RudderStack Web App Types
95
96	```typescript
97	// Found in src/types/workspace.ts
98	enum BillingPlan {
99	FREE = 'free',
100	STARTER = 'starter',
101	GROWTH = 'growth',
102	ENTERPRISE = 'enterprise',
103	}
104
105	enum Region {
106	US = 'us',
107	EU = 'eu',
108	}
109
110	// Found in src/types/transformation.ts
111	type TransformationLanguage = 'javascript' \| 'python';
112
113	// Found in src/types/audience.ts
114	enum ConditionGroupType {
115	AND = 'and',
116	OR = 'or',
117	AUDIENCE = 'audience',
118	}
119	```
120
121	## Phase 2: Map Types to YAML
122
123	Translate discovered code types to tracking plan YAML.
124
125	### Enum to Property
126
127	```typescript
128	// Code
129	enum BillingPlan {
130	FREE = 'free',
131	STARTER = 'starter',
132	GROWTH = 'growth',
133	ENTERPRISE = 'enterprise',
134	}
135	```
136
137	```yaml
138	# Tracking plan property
139	version: "rudder/v1"
140	kind: "property"
141	metadata:
142	name: "properties"
143	spec:
144	name: "billing_plan"
145	type: "string"
146	description: "Organization billing plan"
147	config:
148	enum:
149	- "free" # Exact match to BillingPlan.FREE
150	- "starter" # Exact match to BillingPlan.STARTER
151	- "growth" # Exact match to BillingPlan.GROWTH
152	- "enterprise" # Exact match to BillingPlan.ENTERPRISE
153	```
154
155	### String Union to Property
156
157	```typescript
158	// Code
159	type TransformationLanguage = 'javascript' \| 'python';
160	```
161
162	```yaml
163	# Tracking plan property
164	version: "rudder/v1"
165	kind: "property"
166	metadata:
167	name: "properties"
168	spec:
169	name: "transformation_language"
170	type: "string"
171	description: "Programming language of transformation"
172	config:
173	enum:
174	- "javascript"
175	- "python"
176	```
177
178	### Interface to Custom Type
179
180	```typescript
181	// Code
182	interface Product {
183	id: string;
184	name: string;
185	price: number;
186	category: ProductCat

People who liked this also viewed

6 picks

Type

rudder-code-first-instrumentation

18stars0forks

View on GitHub

How to install rudder-code-first-instrumentation?

rudderlabs/rudder-agent-skills/rudder-code-first-instrumentation

$npx -y skills add rudderlabs/rudder-agent-skills --skill rudder-code-first-instrumentation

Installs into the current project.

Summary

Derives tracking plans from existing codebase types and structures. Use when instrumenting an existing product that wasn't well-instrumented or restructuring existing tracking.

Files · 1

View on GitHub

SKILL.md

1	# Code-First Instrumentation
2
3	This skill guides instrumentation planning for existing products where you derive tracking plans from the codebase's existing types and structures.
4
5	## When to Use This Skill
6
7	\| Scenario \| Use This Skill? \|
8	\|----------\|-----------------\|
9	\| Existing product needs instrumentation \| Yes \|
10	\| Codebase has domain types (enums, interfaces) you want to track \| Yes \|
11	\| Restructuring messy existing tracking \| Yes \|
12	\| Building new feature, events not yet defined \| No — use `rudder-design-first-instrumentation` \|
13
14	## Why Code-First?
15
16	When a product already exists, the code contains valuable type information:
17
18	- Enums define valid values (billing plans, user roles, feature types)
19	- Interfaces define object shapes (product, user, workspace)
20	- Domain models define relationships and constraints
21
22	Deriving tracking plans from code types:
23	- Eliminates translation/mapping layers
24	- Ensures warehouse data matches code semantics
25	- Enables compile-time validation of instrumentation
26	- Keeps tracking plan in sync with product evolution
27
28	> "If I say plan, that cannot mean many things. It's the plan. I have to be specific."
29
30	## The Code-First Workflow
31
32	```
33	┌─────────────────────────────────────────────────────────────────────┐
34	│ CODE-FIRST INSTRUMENTATION │
35	└─────────────────────────────────────────────────────────────────────┘
36	│
37	▼
38	┌─────────────────┐
39	│ 1. DISCOVER │ ← Identify domain types in codebase
40	│ CODE TYPES │
41	└────────┬────────┘
42	▼
43	┌─────────────────┐
44	│ 2. MAP TYPES │ ← Translate code types to tracking plan types
45	│ TO YAML │
46	└────────┬────────┘
47	▼
48	┌─────────────────┐
49	│ 3. IDENTIFY │ ← What user actions should be tracked?
50	│ EVENTS │
51	└────────┬────────┘
52	▼
53	┌─────────────────┐
54	│ 4. BUILD │ ← Create YAML referencing the types
55	│ TRACKING │
56	│ PLAN │
57	└────────┬────────┘
58	▼
59	┌─────────────────┐
60	│ 5. VERIFY │ ← TypeScript compilation validates alignment
61	└────────┬────────┘
62	▼
63	┌─────────────────┐
64	│ 6. TEST & APPLY │ ← Verify in dev workspace, apply to prod
65	└─────────────────┘
66	```
67
68	## Phase 1: Discover Code Types
69
70	Scan the codebase for domain types that should flow through to analytics.
71
72	### What to Look For
73
74	\| Type Category \| Examples \| Tracking Plan Equivalent \|
75	\|---------------\|----------\|-------------------------\|
76	\| Enums \| `BillingPlan`, `UserRole`, `Region` \| Property with enum config \|
77	\| String unions \| `type Status = 'active' \\| 'inactive'` \| Property with enum config \|
78	\| Interfaces \| `Product`, `Workspace`, `User` \| Custom type \|
79	\| Constants \| `PLAN_TYPES`, `REGIONS` \| Property enum values \|
80
81	### Discovery Commands
82
83	```bash
84	# Find enums in TypeScript codebase
85	grep -r "enum " --include=".ts" --include=".tsx" src/
86
87	# Find type unions
88	grep -r "type.=" --include=".ts" src/ \| grep "\|"
89
90	# Find interfaces that might be tracked
91	grep -r "interface.{" --include=".ts" src/types/
92	```
93
94	### Example: RudderStack Web App Types
95
96	```typescript
97	// Found in src/types/workspace.ts
98	enum BillingPlan {
99	FREE = 'free',
100	STARTER = 'starter',
101	GROWTH = 'growth',
102	ENTERPRISE = 'enterprise',
103	}
104
105	enum Region {
106	US = 'us',
107	EU = 'eu',
108	}
109
110	// Found in src/types/transformation.ts
111	type TransformationLanguage = 'javascript' \| 'python';
112
113	// Found in src/types/audience.ts
114	enum ConditionGroupType {
115	AND = 'and',
116	OR = 'or',
117	AUDIENCE = 'audience',
118	}
119	```
120
121	## Phase 2: Map Types to YAML
122
123	Translate discovered code types to tracking plan YAML.
124
125	### Enum to Property
126
127	```typescript
128	// Code
129	enum BillingPlan {
130	FREE = 'free',
131	STARTER = 'starter',
132	GROWTH = 'growth',
133	ENTERPRISE = 'enterprise',
134	}
135	```
136
137	```yaml
138	# Tracking plan property
139	version: "rudder/v1"
140	kind: "property"
141	metadata:
142	name: "properties"
143	spec:
144	name: "billing_plan"
145	type: "string"
146	description: "Organization billing plan"
147	config:
148	enum:
149	- "free" # Exact match to BillingPlan.FREE
150	- "starter" # Exact match to BillingPlan.STARTER
151	- "growth" # Exact match to BillingPlan.GROWTH
152	- "enterprise" # Exact match to BillingPlan.ENTERPRISE
153	```
154
155	### String Union to Property
156
157	```typescript
158	// Code
159	type TransformationLanguage = 'javascript' \| 'python';
160	```
161
162	```yaml
163	# Tracking plan property
164	version: "rudder/v1"
165	kind: "property"
166	metadata:
167	name: "properties"
168	spec:
169	name: "transformation_language"
170	type: "string"
171	description: "Programming language of transformation"
172	config:
173	enum:
174	- "javascript"
175	- "python"
176	```
177
178	### Interface to Custom Type
179
180	```typescript
181	// Code
182	interface Product {
183	id: string;
184	name: string;
185	price: number;
186	category: ProductCat

People who liked this also viewed

6 picks

Type