# Writing the change list safely

The audit never edits the property. Fixes leave as a change list that a person with the named role applies. GA4 has no versions or rollback, so every item must say what can and cannot be undone. Template: [../assets/change-list-template.md](../assets/change-list-template.md).

## Rules for the list

- One change request per hypothesis. "Purchase is counted once per session" is one request; tidying custom dimensions is another.
- Order P1 to P4 ([scoring.md](scoring.md#change-priority)), then by key events affected.
- Quote the current value from the snapshot or intake row and name the resource, for example `properties/123456789/keyEvents/2001 countingMethod ONCE_PER_SESSION`.
- State reversibility from the register below. There is no rollback version to cite.
- Name what could break: audiences, explorations, Google Ads goals and imports, warehouse models, dashboards and alerts.
- A test that creates GA4 events runs on staging or a test property with approval. Filters are tested in Testing state. Data API rechecks wait 24 to 48 hours.
- When a fix lowers or raises a reported number, say which metric moves, roughly how much, and who is told before release, so a correction is not read as a performance change.
- Every item carries annotation text for the date it ships.
- A person with the named role applies the change. This skill never writes.

## Irreversibility register

- Activate an Exclude or Include data filter: not reversible for data processed while Active; that data is never processed and never reaches BigQuery (answer 13296761).
- Archive a custom dimension or metric: not reversible; audiences that use it stop accumulating users (answer 12436143).
- Reduce data retention: reversible only within 24 hours; after that, data older than the new period is deleted at the next monthly process (answer 7667196).
- Increase data retention: reversible; applies only to data not yet deleted.
- Change the reporting attribution model: reversible, but it rewrites historical reports in both directions (answer 10597962).
- Change lookback windows: forward only.
- Change a key event counting method: forward only (answer 13366706).
- Mark or unmark a key event: forward only; earlier data keeps its old marking (answer 13128484).
- Set a primary channel group: forward only; custom groups themselves apply to history (answer 13051316).
- Change the property time zone: forward only; a flat spot or spike on the change day.
- Switch reporting identity: reversible, no permanent effect (answer 10976610).
- Unlink Google Ads: relinking restores the flow, but imports stop while unlinked (answer 9379420).
- Change the BigQuery dataset location: prefer cross-region dataset replication (copy or move), which keeps the link and avoids a gap; deleting and recreating the link leaves a gap (answer 9823238).
- Remove an expiration from BigQuery daily tables: reversible, but tables already expired are gone; a new dataset default does not change existing tables, so each table's expiration is updated too (BigQuery dataset docs).
- Exclude events or streams from the BigQuery export: forward only; exported days keep their content. Verify at run time whether excluded days can be refilled.
- Enhanced measurement, redaction, unwanted referrals, domains and session settings: the setting can be reverted; data collected in between keeps the old behaviour (inferred; verify).
- Delete a data stream or property: never part of this skill.

## Roles

- Data filters, internal traffic, unwanted referrals, domains, redaction, retention, archiving: Editor at property level.
- Key event marking, counting method, attribution settings: Marketer or above. Google's marking page and its roles page disagree on Editor versus Marketer for existing events; check the person's effective role.
- Reporting identity: Editor at account level.
- Google Ads link: Editor in GA4 and administrative access in Google Ads.
- BigQuery link: Editor in GA4 and the Cloud project permissions in Google's setup guide.
- Verify each role at run time; the help pages were read on 2026-11-01.

## Annotations

- One per shipped change: the date, a title of at most 60 characters, a description of at most 150 characters.
- Orange is reserved for Google's system annotations; pick another colour.
- A human writes them in GA4. The GA4 MCP server can create annotations only when started with `--allow-write`, which this skill never uses.
- The report's "Proposed annotations" section also lists past changes that were never annotated.

## Worked change requests (fictional Acme Store, properties/123456789)

```markdown
### CR-1 Stop emails reaching GA4 from the newsletter confirmation URL (P1, G24 FAIL)
- Entity: page /newsletter/confirm on www.example.com; properties/123456789/dataStreams/1234567890/dataRedactionSettings
- Current value: R15 found 312 page_view events whose page_location carries an email under the key email
  (values not copied); emailRedactionEnabled false, queryParameterRedactionEnabled false.
- Change: 1) the site team stops putting the email in the URL (post the form, or use an opaque token);
  2) turn on email redaction and query parameter redaction with the key email on Acme web.
- Why: Google's policy prohibits sending personal data to Analytics; redaction is a client-side safety net
  and does not cover Measurement Protocol.
- Reversible: the settings yes; data already collected stays. The privacy owner decides what to do about it.
- Could break: nothing that is correct today. Reports grouped by page_location lose the email variants.
- Depends on: none. Role needed: Editor (redaction); site release owner (URL).
- Test: the stream's redaction test with the fictional URL
  https://www.example.com/newsletter/confirm?email=jane@example.com shows the value redacted; after the
  release, R15 over two full days returns zero rows for this path.
- Test approval and data: no live form submission needed; the redaction test sends nothing.
- Annotation: 2026-11-10, "Email removed from newsletter URL; redaction on",
  "Site change plus email and query parameter redaction on Acme web. Page counts by URL shift."
- Owner sign-off: privacy owner, web analytics lead.

### CR-2 Keep the Developer traffic filter in Testing until debug_mode is removed (P1, G07 FAIL)
- Entity: data filter "Developer traffic", type developer, state Testing since 2026-08-12.
- Current value: R11 shows it would match 61% of events.
- Change: none in GA4 now. A person with Edit access removes the debug_mode parameter that gtm-container-audit
  found in production tags. After 24 to 36 hours, read R11 again; activate only when the match share is under 5% and the matched
  events are debug sessions.
- Why: a debug_mode parameter set to false still enables debug mode, so activation would delete real data.
- Reversible: activation is not; data processed while Active is never processed.
- Could break: nothing while the filter stays in Testing; DebugView keeps working either way.
- Depends on: the GTM change list item that removes debug_mode. Role needed: Editor, with measurement owner sign-off.
- Test: R11 testDataFilterName by eventName, with hostName added, after the GTM release.
- Test approval and data: none needed; data rechecks only.
- Annotation: on activation day, "Developer traffic filter activated", "Debug traffic now excluded from reports and BigQuery."
- Owner sign-off: measurement owner.

### CR-3 Remove auto-marked session_start and ecommerce steps from key events (P2, G11 FAIL)
- Entity: properties/123456789/keyEvents for session_start, view_item, view_item_list, add_to_cart,
  add_to_wishlist, begin_checkout, view_search_results (custom false, deletable true, created 2024-02-20).
- Current value: all seven marked; session key event rate 99.6%.
- Change: first confirm with the GAQL in data-checks.md that no Google Ads action imports these events;
  then unmark the ones the measurement owner does not keep. Verify whether Google re-marks them while ads
  personalization stays on.
- Why: totals of all key events are dominated by session_start and browsing steps.
- Reversible: forward only; earlier data keeps the old marking.
- Could break: Google Ads actions imported from these events, explorations that read all key events.
- Numbers expected to move: key events fall by about 4.5 million per 28 days; the session key event rate falls
  from 99.6% to the share of sessions with a real outcome. Tell the reporting owner first.
- Depends on: none. Role needed: Marketer or above.
- Test: R01 isKeyEvent per event on the second day after the change.
- Test approval and data: none needed; data rechecks only.
- Annotation: change day, "Browsing events unmarked as key events", "session_start and six ecommerce steps are no longer key events; totals fall."
- Owner sign-off: measurement owner; Google Ads owner confirms no import uses these events.

### CR-4 Count purchase once per event (P2, G12 FAIL)
- Entity: properties/123456789/keyEvents/2001 (purchase), created 2023-06-02 by goal migration.
- Current value: countingMethod ONCE_PER_SESSION; R01 purchase keyEvents 9,620 against eventCount 9,800.
- Change: countingMethod ONCE_PER_EVENT (check at run time that the screen offers it for this key event).
- Why: two purchases in one session are two orders; once per session drops the second.
- Reversible: forward only.
- Could break: period comparisons of purchase key events across the change date.
- Numbers expected to move: purchase key events rise from about 9,620 to about 9,800 per 28 days (+1.9%), matching purchase events.
- Depends on: none. Role needed: Marketer or above.
- Test: R01 keyEvents equals eventCount for purchase two days after the change.
- Test approval and data: none needed; data rechecks only.
- Annotation: change day, "Purchase counted once per event", "Repeat purchases in a session now count; purchase key events rise about 2%."
- Owner sign-off: measurement owner.
```

## Release evidence to ask for

The person who applies an item closes it with three answers:

- Did the setting change as written? (a screenshot of the setting after the change)
- Did the data change as expected? (the named R report two days later)
- Did downstream consumers keep working? (Google Ads import status, warehouse model row counts, dashboards)

A yes to the first does not stand in for the other two.