# Reconciliation: dispositions, plan changes and the change list

The audit ends with three files for people to act on: the findings report, a reconciled plan draft, and an ordered change list. Nothing is applied by the agent.

## Contents

- Dispositions
- Fix the code or fix the plan
- Change classes and approvers
- The reconciled plan draft
- Change list rules
- Release evidence
- Monitors to propose

## Dispositions

Give every FAIL and WARN exactly one.

- Fix implementation: the plan is right and the data is wrong. The default for D04, D06, D07, D10, D12, D13, D14 and a stopped D01. A D15 registration fix is tool configuration in GA4 Admin.
- Amend plan: the plan is wrong for the business fact or lags the release. A legitimate new enum value, a status that lags, a type that cannot hold the fact (money planned as integer with no minor units).
- Adopt into plan: an unplanned event or property with a consumer or a real use. Write its contract with tracking-plan-builder; status implemented until its acceptance tests pass.
- Retire: no consumer, no planned use, and every emitter root searched ([emitter-search.md](emitter-search.md)). Sequence, never shortened:
  1. Owner approval for the tier.
  2. Stop emission at the source.
  3. Zero rows in each tool for 7 consecutive days; for mobile, until the old-version share is under the agreed exception.
  4. Only then block or delete in a tool. Mixpanel, Segment and Amplitude all state that data blocked or rejected while blocked cannot be recovered.
  5. Set the plan status to retired with the date, and keep the contract.
- Rename or merge: follow event-naming-convention's migration procedure. Tool-side merges and display names are stopgaps; the raw data stays split.
- Accepted exception: recorded in `decisions.md` with an owner and an expiry date; the metric excludes the affected rows; the report cites the entry. Downgrading a FAIL needs this citation.
- Needs decision: the question, the owner and a due date go in the report's decisions section.

## Fix the code or fix the plan

- Types are fixed at the emitter. Change the plan type only when the plan is wrong for the business fact.
- Canonical name in a variant pair: the plan's name when consumers use it; otherwise the spelling consumers use. Never decide by volume or naming style.
- Two producers of one name: the contract's source of truth wins. The other producer is removed, or becomes a companion with its own name and its own transport key.
- Enum drift: a legitimate new value owned by the product amends the plan as a compatible change, after the enforcement copies list it. A value the emitter maps wrongly is an implementation fix.
- Copy drift: data blocked or flagged because an enforcement copy is stale is fixed in the copy, not in the code. Before any copy is switched to block or reject, send one legitimate new event and one invalid event through it in a test source; a stale copy rejects valid production data, and rejected data cannot be recovered.
- Never rename an established, consistent taxonomy only for style. Record the convention in `naming-rules.md` and `decisions.md` instead.
- A verified event that fails the audit goes back to implemented until its acceptance tests pass again.
- Not shipped is not broken: proposed and approved events are not expected yet. Implemented or verified events with no rows are defects or wrong statuses.

## Change classes and approvers

Classes are tracking-plan-builder's, so the two skills agree:

- Correction: the implementation now matches the approved contract. No version change; record the affected date range so analysts know which data was wrong.
- Documentation: description, owner, status. No effect on emitted data.
- Compatible: a new optional property, a new allowed value with its own reporting bucket, a new destination. Update the enforcement copies before release; no version bump.
- Breaking: trigger, must-not-fire condition, grain, required property, type, identifier, or a removed allowed value. Bump the contract version.
- Rename: the raw name changes. Treat it as a consumer migration with a release boundary.

Approvers by risk tier, and a change inherits the higher of the contract's tier and its own:

- Tier 1 (revenue, ad conversions, CRM workflows, identity, consent): business, data and implementation owners, plus the privacy reviewer when a personal field or consent behaviour changes.
- Tier 2: data and implementation owners.
- Tier 3: the data owner.

## The reconciled plan draft

- Start from `plan-changes-draft.csv`, which `audit_plan.py drift --out DIR` writes with default dispositions and the finding IDs. Columns: [../assets/plan-changes-template.csv](../assets/plan-changes-template.csv). Every row stays status draft.
- Replace each "decide:" proposal with the decision once the owner answers, and set the change class, version bump and approver role.
- Prepare draft copies of the two tabs with the changes applied, or per-contract diffs for YAML plans, in a scratch folder. Never overwrite the canonical plan; the script refuses to write inside `martech-context/`.
- Draft the CHANGELOG entry: date, contract, class, release, consumers updated, approvers.
- Retired and deprecated items stay in the plan with their dates.
- Check: every finding whose disposition edits the plan has a plan-changes row, and no row exists without a finding.

## Change list rules

Template: [../assets/change-list-template.md](../assets/change-list-template.md).

- One hypothesis per change request. One request can close several findings: a second producer and the completeness FAILs it causes are one request.
- Order: privacy; double counting and wrong values; missing data; plan amendments; hygiene in a separate release.
- Name the entity by tool, event and property, and quote the current state from the inventory with numbers, denominator and window. `findings.csv` gives `affected` with its `unit` (for D07, the rows without the property), plus `denominator`, `share_pct` and `last_seen` where the rule has them.
- Name the system to change: application code, tag manager, CDP mapping or destination filter, tool configuration, enforcement copy, warehouse model, or plan only.
- Tests come from tracking-plan-builder's acceptance catalogue, with evidence per layer: emission, collection, destination, warehouse, use. A negative case may record one line naming every layer it was checked in.
- Rollback, and what it does not undo: when a fix touched both the application and a tag manager container, roll back to a compatible pair, never one side alone. Data already collected stays split or wrong, blocked data is gone, plan copies changed separately stay changed.
- When a fix will lower a reported number (removing a second producer), say so in the request and tell the reporting owner before release, so a correction is not read as a drop in performance.
- Tests that submit forms, orders or consent choices on a live site need the user's approval, staging or a flagged test account, and agreed test references. List the records each test creates.
- If someone wants the changes applied through an MCP server, the agent-write-safety skill applies first. This skill does not write.

## Release evidence

The person who applies a request closes it with three answers:

- Did the change go in as written? (diff, commit, container version comparison)
- Did runtime behaviour match? (a test-account payload per case)
- Did each destination receive the event once with the planned types? Re-run the inventory for the event over 7 days or 1,000 events, whichever is later. The rule that failed must pass on evidence, not because rows are absent.

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

## Monitors to propose

Turn the findings into monitors and hand them to tracking-monitoring-and-incidents (planned) or the vendors' own alerting:

- Required completeness: alert below 100% on tier 1 server events; on client events, below the trailing 28-day level.
- Unknown enum value: alert on the first value outside the list under reject or send_unknown_and_alert.
- Ratio to the system of record: alert above 1.0, or outside the documented band for a browser route.
- Stopped sending: zero rows for a day on a tier 1 event.
- New unplanned event in any audited tool.
- Vendor options to check in the live docs before naming them in a plan: Segment violation forwarding, Mixpanel Data Volume Monitoring, Amplitude Data's unexpected-event handling, Avo Inspector issues, GA4 custom insights.