# Instrumentation context

<!--
Template for .amplitude/instrumentation-agent-context.md at the repo root
(or at the root of the sub-tree being instrumented). Amplitude's
instrumentation skills read this optional file and treat it as the
customer's conventions. Keep it short and point to the approved plan
instead of copying it, so there is one source of truth.
Remove this comment before committing.
-->

## Source of truth

- The approved tracking plan lives in `martech-context/tracking-plan/`. Each `<event_name>.yaml` file is the contract for one event.
- Only events with `status: approved` or later may be instrumented. Propose any other event to the data owner instead of adding it.
- Shared property definitions: `martech-context/data-dictionary.md`
- Naming rules: `martech-context/naming-rules.md`

## Conventions

- Event names: lowercase snake_case, object then past-tense action (`report_generated`). The Amplitude event type is the value under `destinations.amplitude.name` in the contract, which is normally the canonical name.
- Property names: lowercase snake_case. Types and allowed values come from the contract; do not add values that are not listed.
- Fire only on the `trigger` in the contract and never on any `must_not_fire` condition. Backend facts are sent from the backend, not the UI.
- Set `insert_id` to the contract's `message_id`, never to `event_id` itself. `message_id` is the UUIDv5 of `event_id`, the emitted event name and the emitter, under the plan namespace in `martech-context/decisions.md`; it is created once when the fact occurs and reused on every retry. Send `event_id` as an event property when the contract lists companion events.
- When events reach Amplitude through a CDP, the CDP mapping sets `insert_id`; follow the contract's `destinations.amplitude.dedupe_mapping` instead of setting it in code.
- Set `time` to the contract's `occurred_at` in milliseconds since epoch.
- `user_id` is the internal user id (never an email). Keep the existing `device_id` when the user logs in.

## Never send

- Email addresses, names, phone numbers, free text, tokens, credentials or URLs with query strings.
- Any field listed under `pii_exclusions` in a contract.

## Reference files

- martech-context/tracking-plan/<journey-slug>.md
- martech-context/tracking-plan/CHANGELOG.md