| name | form-telemetry-and-control |
| description | Define a form's measurement contract before instrumenting it: which events, which denominator, what counts as a defect, how per-field drop-off lies, and how to hand an individuals series to statistical process control without manufacturing false signals on a low-volume form. |
Skill: form-telemetry-and-control
Invoked by: process-improvement/process-analyst (when the process being baselined starts at a web form), web-design/ux-designer, and marketing-operations work that needs a form number to mean something.
When to invoke: before instrumenting a form; when two dashboards disagree about the same form's completion rate; when someone proposes charting a form metric; when a form "improved" and nobody can say against what.
Output: a populated ../../templates/form-telemetry-plan.md, and — where the volume supports it — an individuals series handed to process-improvement for charting.
[NOVEL SYNTHESIS — applying SPC to form telemetry is our synthesis, not established practice. We found no published work joining web-form telemetry to SPC/DMAIC (open-web search, 2026-08-17); the negative finding is bounded by that method and is not proof of universal absence.]
⛔ That marker is load-bearing, not decorative. The metric definitions in this skill are ordinary web analytics. The join to statistical process control is ours, and a reader is entitled to know that before they present a control chart of a form metric to a stakeholder as standard practice.
The discipline in one sentence
A form number without a named denominator and a named defect definition is a decoration.
Not this skill
Step 1 — Fix the denominator, in writing, first
Three plausible denominators; they do not agree; the choice is not recoverable after the fact. The definitions and the platform defaults are in ../../knowledge/form-telemetry-and-spc.md §1.
The default is form starts, defined as first interaction with a field. Write the definition into the plan in words a second analyst would implement identically. Then state completion and abandonment as exact complements on that one denominator, and never quote them from different ones. See ../../best-practices/name-the-denominator-before-you-quote-a-completion-rate.md.
Step 2 — Enumerate the events, and what each one does not mean
At minimum: view, start, per-field first-interaction, validation-error, submit attempt, server acceptance.
The two gaps that cause most confusion:
- A submit event is not an acceptance. Instrument the server's acceptance separately or you cannot distinguish "the form worked" from "the form posted".
- A validation error is not a defect until you say which errors count. A user mistyping their own email is not a form defect; a valid address rejected by an over-tight pattern is.
Identify each form distinctly. On a platform where the form identifier arrives as an event parameter rather than a dimension, that registration is a setup step — until it is done, every form on the property is one undifferentiated series.
Step 3 — Define the defect
Three classes, three owners — validation, delivery, triage. The operational definitions are in ../../knowledge/form-telemetry-and-spc.md §4. Pick the ones you will count and write the definition down before the first observation, not after the first argument.
⛔ Abandonment is not automatically a defect. Someone who discovers on the form that they are in the wrong place and leaves is a success. Counting them as defects makes the metric worse the better the form gets at qualifying people.
Step 4 — Collect per-field data, and label it as a proxy wherever it goes
Per-field error rate is a real measurement. Per-field drop-off is a proxy for "the field that caused the exit" and has not, as far as we can establish, been validated as such — see ../../knowledge/form-telemetry-and-spc.md §3.
../../scripts/form_metrics.py prints that caveat in its own output header. Keep it attached when the number moves into a slide.
Step 5 — Compute the numbers with the script, not by hand
python3 plugins/forms-engineering/scripts/form_metrics.py path/to/sessions.csv
Emits starts, submits, completion and abandonment with the denominator printed, time-to-complete for completers, per-field error rate, and per-field last-touch drop-off carrying its proxy label. The synthesis marker goes to stderr in every mode, so it reaches a human without polluting a pipe.
Step 6 — Hand the individuals series over. Do not chart it here.
python3 plugins/process-improvement/scripts/lss_calc.py imr \
--values "$(python3 plugins/forms-engineering/scripts/form_metrics.py --emit-imr path/to/sessions.csv)"
--emit-imr writes numbers only to stdout — no header, no banner — precisely so that substitution works. The arithmetic belongs to lss_calc.py, which is verified and gated; nothing statistical is reimplemented here.
⛔ Command substitution, not a pipe. lss_calc.py imr requires --values and reads no stdin; a piped form discards the left side and exits non-zero.
⛔ Below 20 individual observations, do not chart it at all. --emit-imr refuses under that floor. Form series are low-volume and autocorrelated by weekday and campaign; naive three-sigma limits on such a series manufacture false special-cause signals, and reacting to them is tampering. The rule and its reasoning: ../../best-practices/do-not-put-three-sigma-limits-on-a-low-volume-form-series.md.
Step 7 — Say what would change your mind
Write, in the plan, the observation that would falsify the improvement you expect. A measurement plan whose every possible outcome is consistent with success is not a measurement plan.
