The schema comes before the component

You have five defined metrics and, next to each, the signal that would settle which of its two readings is true. Dwell before approve. A field edited and reverted. The source crop never opened. A review walked away from. Now you open HouseWarm’s gate to add the analytics, and the list stops being a list of decisions and becomes a list of things the code cannot tell you.

Take the revert. Under the definitions the metric-set module settled on, correction rate compares the reviewer’s submitted value to the agent’s proposed value, so a field touched and put back is not a correction. Fine. You wanted the revert as a separate event anyway. But the field is an ordinary controlled input: it holds the current value and a change handler. By the time the approve fires, the submitted value is all there is. Nothing in the component ever knew that the value had moved away from the agent’s proposal and come back, because nothing in the component was ever asked to remember the proposal.

You cannot add that event. You can only add the component state it requires, and then add the event. That is a change to how the field works, made for a reason that has nothing to do with what the field looks like, and it is a change somebody has to agree to. This is the whole lesson: an event schema is either a constraint on how the surface gets built, or it is a wish list filtered by whatever the surface happened to expose.

This argument is the course’s own

Say that plainly, because the alternative is worse. There is no study showing that teams who write an event schema first end up with better metrics than teams who retrofit one. The claim rests on a mechanism, not on evidence: a retrofit can only observe what already shipped, so the set of measurable things is decided by component decisions made for unrelated reasons. That is an argument you can check for yourself in an afternoon by trying to compute dwell from a gate that does not emit it.

Searching for an independent authority on this turns up tracking-plan and schema-governance guides from Segment, Amplitude and mParticle — every one of them a vendor recommending a practice its own product exists to sell. None of them is cited here, and none of them should be cited by you either, because a vendor advocating for the discipline its tooling implements is not evidence that the discipline works. The argument stands on its own logic or not at all.

What a schema row actually contains

Six columns, which is exactly section 1 of the instrumentation spec. An event is not finished until all six are filled:

• Name. Stable, lowercase, object then past-tense verb: field_reverted, evidence_opened, review_abandoned. Treat it the way this site treats a route segment — a permanent address. Renaming an event splits its history in two and nobody notices until a chart has a cliff in it.
• Fires when. The precise trigger, in a sentence a front-end engineer can implement without asking you a question. “When the reviewer opens the source crop” is not precise: on click, or on the crop entering the viewport, or on it being visible for some duration? Pick, and write the pick down.
• Properties, with types. Names and types, not examples. confidence_bucket: enum, not confidence: 0.83.
• Feeds metric. Which of the five, by name. An event that feeds nothing is data you decided to collect about a person for no stated reason, which is a problem the never-logged lesson takes seriously.
• Question it answers. One sentence. If the honest answer is “it might be useful later,” delete the row.
• Destination. Analytics, the trace, or both. The routing lesson is entirely about this column, and it is the column that most often turns a defined metric into an uncomputable one.

Three tests a row has to pass

Run every proposed event through these before it reaches an engineer. Each one kills a specific way schemas go wrong.

1. A metric names it. Some row in section 2 lists this event under “events required.” If none does, the event is collection without a purpose.
2. A component can emit it, and you have said which. Not “the gate emits it” — the field component, the crop disclosure, the session wrapper. If no component is in a position to know the thing, you have found a component change, and it belongs on the build plan rather than in the analytics ticket.
3. No property touches the never-logged list. Section 3 of the spec is a constraint on section 1, not a separate document. A property that carries document content fails here and gets replaced by a derived shape, which is the never-logged lesson’s whole subject.

Write down what you are not going to measure

The framework this lesson points at is a risk-management standard, not an analytics guide, and the requirement worth stealing from it is small and unglamorous. Under MEASURE 1.1, NIST asks that approaches and metrics be selected and documented, and that the characteristics that will not or cannot be measured be documented as well. Not measured, written down, on purpose.

That section exists for a reason the same document states outright: measurement approaches “can be oversimplified, gamed, lack critical nuance, become relied upon in unexpected ways, or fail to account for differences in affected groups and contexts,” against a background it describes as a current lack of consensus on robust and verifiable measurement methods. And the line that keeps the list honest — an inability to measure a risk does not imply the risk is low.

For a review gate, the will-not-measure section is short and specific. Omission errors: the field the agent never flagged and the reviewer never looked at leaves no trace, so the correction rate is computed entirely from errors of commission and the schema should say so. Whether a correction was right: the gate observes that the reviewer changed a value, never that the new value is correct. Reviewer confidence: no event observes it, and inferring it from dwell would be inventing a measurement. Writing those three lines takes five minutes and stops a year of somebody quoting correction rate as an accuracy figure.

The retrofit’s favourite move, and why it fails

When the events are missing, the reconstruction is always the same: derive them from the timestamps you do have. Dwell becomes the gap between document_opened and document_approved. It is free, it needs no component change, and it produces a number for every document you have ever reviewed.

It is also wrong in a direction you cannot bound. That interval contains lunch. It contains the tab sitting behind a Slack window, the reviewer answering the phone, the machine asleep. Without a visibility signal and an idle threshold, a ninety-second review and a nine-minute one are indistinguishable from a reviewer who left the tab open, and the distribution you get has a long right tail that means nothing. Worse, it is plausible: nobody looking at the chart can tell that the number is uncomputable, because it has the shape a real dwell distribution would have.

That is the general failure. A retrofitted metric is not obviously broken. It is a number, with a name, in a dashboard, and the person reading it has no way to know that its definition was set by what the components happened to expose rather than by what the question required.

What this does not cover

The schema now says what has to be emitted and by which component. It does not say where those signals come from, and the answer matters more than it sounds: most of the events you just wrote have no backend equivalent at all. A server that hears about extractions and approvals knows nothing about hesitation, a revert, an unopened crop or a review that ended without a decision.

The client-signals lesson takes those four in turn — what each one disambiguates, what a component has to do to observe it, and where the course is inferring rather than citing. The never-logged lesson then constrains the property lists you just wrote, and the routing lesson fills in the destination column you left blank.