---
name: customer-data-template
description: Draft or audit a customer data tracking plan — events, identity, context, and governance — using the six-questions method. Use when designing analytics events, reviewing an existing tracking plan, naming events and properties, wiring a CDP source, or deciding what a product should measure.
---

# The customer data template

A tracking plan is a contract, not a catalogue. This skill teaches you to write
one that a team can actually keep — and to audit one that a team has quietly
stopped keeping. It was taken from the shelf of The Data World Store
(rafaelwashington.com/data-world) — the site it came from runs on the very
plan this template generalises.

Work through the eight parts in order. Every part ends with a rule you must not
bend; when the user's situation seems to demand bending one, say so out loud
and name the cost instead of bending it silently.

## 1. Start with questions, not events

Before naming a single event, write down the questions the business will act
on. Six is a healthy number; more than ten means nobody will act on most of
them. Each question must name who acts on the answer and what they would do
differently.

| Question | Who acts | Acting looks like |
| --- | --- | --- |
| Does anyone finish the journey, or bounce at step X? | e.g. Product | Reorder or cut the step |
| Which segment converts best, and where do the others leak? | e.g. Growth | Shift spend, rewrite the entry point |
| … | … | … |

**The rule:** an event that answers none of the questions is not in the plan.
That filter is the whole template — it is why there is no `Button Clicked`.
This is also what "actionable data" means: not data you could act on, but data
someone has already agreed to act on.

## 2. The naming contract

Straight out of the Segment spec, and non-negotiable — a plan you bend is a
plan you do not have:

- **Events** — Object + Action, Title Case, past-tense verb. `Product Added`,
  `Signup Completed`. Never dynamic: variability belongs in properties, so
  `Pro Plan Selected` is wrong and `Plan Selected { plan: "pro" }` is right.
- **Properties** — `snake_case`, always. Typed, with closed enums wherever the
  value set is knowable.
- **Traits** — `snake_case`, on `identify` only.
- **Reserved names carry reserved shapes.** If the product has a real cart, use
  the Ecommerce spec names and take the spec's property shapes with them.
  Anything that is not genuinely a spec behaviour gets a custom Object–Action
  name. A plan that lies about its semantics is worse than one that admits it
  has custom events.
- **Timestamps** are ISO 8601, UTC, set by the library, never by a caller.
- **Money** is a number plus an explicit `currency`. Never a formatted string.

## 3. Identity — the one honest moment

Three layers, never confused with each other:

- **Anonymous** — the SDK's `anonymousId` is authoritative. Do not mint your
  own device id alongside it.
- **Known** — `identify` fires at the moments a person genuinely tells you who
  they are (signup, login, a form that asks a name). List those moments in the
  plan. An `identify` anywhere else is a lie about consent. It must carry a
  stable `user_id`; traits without an id attach to nothing and join nothing.
- **Session** — a per-visit id for stitching one sitting together. It is not an
  identity and must never be sent as `user_id`.

**The rule:** every identifier in the stack is a treaty between teams — this is
what it means, this is who owns it, this is when it may change. Write the
treaty table (identifier, meaning, owner, format, may-change-when) before any
identity-resolution tooling is discussed. The tooling only keeps score of how
well the treaties are honoured.

## 4. The event table

One row per event. "Where" is the call site — file and line — so plan and code
can be checked against each other by reading one column.

| Event | Fires when | Properties | Where |
| --- | --- | --- | --- |
| `Signup Completed` | The account exists, once | `method`, `plan` | `auth/complete.ts:88` |

Group rows by journey (acquisition, activation, checkout…) rather than by
team, because journeys are what the questions in part 1 are about.

**The rule:** separate what fires today from what is specced and not yet wired,
in the document itself. A plan that blurs the two is a plan nobody can trust —
and the specced section is where ambition stays honest.

## 5. The property dictionary

Every property, defined once, reused everywhere:

| Property | Type | Notes |
| --- | --- | --- |
| `plan` | enum | `free` \| `pro` \| `enterprise` |
| `value` | number | Plus explicit `currency`, ISO 4217 |

**The rule:** one property, one meaning. If two events need subtly different
meanings, they need two property names — `step` on one event silently meaning
something else on another is how a funnel lies without one false number in it.

## 6. The context layer

Per-event properties answer "what happened". Context answers "to whom, where,
and how far in" — registered once as always-attached context (super
properties, in several vendors' vocabulary) and re-snapshotted when the state
behind them moves. Typical citizens: a stable `visitor_id` join key,
`session_id`, `is_returning`, declared intent, current surface, progress
counters, and any accessibility preference the product's experience actually
varies on.

**The rule:** context is for facts about the visit, not the person. Names,
emails, and anything a person typed stay out of event streams entirely.

## 7. The defect ledger

The template's most unusual part, and the one that buys the most trust: a
numbered list of what is currently wrong, ordered by how much damage each
defect does once a real destination is connected. "identify sends no user id."
"order_id is the session id, so second orders dedupe away." Each defect gets a
fix, and fixed defects stay in the ledger, struck through, with what fixed
them.

**The rule:** the ledger is append-and-strike, never delete. A plan that admits
its faults is the only kind whose clean rows mean anything.

## 8. Governance — how it stays true

A plan drifts the day it ships unless the rituals hold. The four that matter,
in priority order:

1. **The plan lives in the repo.** A new event is a pull request; the review is
   the schema review. Never a wiki page — wikis describe, repos enforce.
2. **A check runs in CI** that fails the build when code and plan disagree, in
   either direction. Type the event map so an unplanned event is a compile
   error; parity-check the vendor JSON against the types. Manual counts do not
   scale — that is how drift is found a quarter late.
3. **Every identifier has one named owner** (a person, not a team). Ownerless
   identifiers are how a "temporary" id format from three years ago is still
   minting profiles today.
4. **A rename is a migration, not an edit** — dated, versioned, with the old
   name's data accounted for. Editing history in place is how two years of a
   funnel quietly become incomparable.

**The rule:** consistency is upstream of accuracy. Teams that agree on what
words mean produce real data by default; teams that do not cannot be saved by
any amount of downstream cleaning.

## When auditing an existing plan

Score it against the eight parts in order, and report in this shape: what the
plan gets right (specific, not polite), the three highest-damage gaps with the
defect-ledger entry each deserves, and the one ritual from part 8 to install
first. Resist the urge to propose new events until the naming, identity, and
governance layers are sound — new rows on a cracked foundation are more drift,
faster.

## When drafting from scratch

Interview first: the six questions (part 1), the identity moments (part 3), and
the teams who will emit events. Then produce the plan as one document in the
order of this template, with the event table split into "fires at launch" and
"specced, not yet wired". Keep the launch set small enough that every event has
an owner who wanted it — under twenty is usually right. The defect ledger
starts populated: write down the compromises made while drafting, because
every plan is born with some, and the ones written down are the ones that get
fixed.