sxchnge/.agents/skills/ux-observability/SKILL.md

name, description

name	description
ux-observability	Define and review end-to-end measurement for important user journeys during user-facing interface work. Select purposeful semantic events and outcome metrics without instrumenting every control.

UX Observability

Important user journeys must be measurable end-to-end. Instrument journeys to understand whether users achieve their goals and where they fail. Do not add events merely because a UI control or screen exists.

Define the journey before implementation

• Identify important journeys before implementing complex or business-critical flows. For smaller UI changes, identify the affected journey and inspect its existing measurement; reuse it when sufficient rather than adding events.
• Inspect existing journey definitions, telemetry, and product conventions. Follow established conventions over generic recommendations unless a concrete problem justifies changing them. Do not prescribe vendors, SDKs, or UI frameworks.
• Define success and UX quality measures before building the flow. Record its start, actual successful outcome, failure states, abandonment rule, and any meaningful intermediate or recovery states needed for diagnosis.
• Define the measurement window and what counts as a journey attempt. Specify how retries or resumed journeys affect counts and duration. Measure abandonment through an explicit exit or a defined period without completion; do not assume every missing completion is abandonment while asynchronous work is pending.
• Measure the actual user outcome whenever possible. A successful local UI action does not prove the underlying operation succeeded. If only a proxy is available, label it and document the measurement gap instead of claiming outcome coverage.
• When reconstruction requires it, correlate events across screens and asynchronous operations with a scoped journey or correlation identifier. Define its lifetime and retry behavior; avoid using sensitive identity data as the identifier.

Choose semantic events

Distinguish these layers:

Layer	Example	Meaning
UI interaction	A submit control is activated	A control was used
User intent	The user requests payment	The user tried to advance a goal
Journey state	Payment is submitted and processing	The operation reached a meaningful stage
Business/UX outcome	Payment is confirmed or fails	The user's goal succeeded or encountered failure

The closer an event is to a meaningful outcome, the more valuable it generally is. Keep intent and completion distinct; one does not imply the other.

• Track semantic actions, meaningful transitions, and outcomes. Prefer a small number of stable, high-value events over exhaustive UI telemetry.
• Avoid indiscriminate click tracking and speculative metrics. Events such as ButtonClicked, DropdownOpened, FieldFocused, FieldChanged, and SubmitClicked should not be added without a clear analytical purpose.
• Prefer events such as payment_started, payment_submitted, payment_succeeded, and payment_failed only when those names correspond to meaningful states in the actual product journey. These are examples, not a required event list. Emit success from evidence of the confirmed outcome.
• Keep event meaning independent of widget names, component hierarchy, screen structure, coordinates, or other UI implementation details. A UI refactor should not invalidate the journey definition or its metrics.
• For each event, record its meaning, emission condition, necessary properties, and known purpose, consumer, or decision supported. Omit events with no such use.

Measure quality with minimal data

• Make it possible to calculate successful completion/conversion, abandonment, drop-off between meaningful steps, duration, failure rate, and relevant error or recovery states. Define denominators and time boundaries so results are interpretable; use only intermediate steps that help diagnose the journey.
• Reuse existing outcome signals where possible. Keep correlation sufficient to reconstruct important journeys without collecting unrelated activity.
• Respect privacy and data-minimization requirements. Collect only properties needed for the stated analytical purpose; do not capture sensitive user data, form contents, or raw error payloads merely to simplify analysis.
• Validate representative success, failure, retry, and abandonment scenarios against emitted or existing signals. Check that retries or duplicate delivery do not inflate outcomes and that cross-screen/asynchronous correlation works. Document unavailable signals or measurement limitations honestly.
• Keep measurement from blocking the user journey or changing its outcome when telemetry is unavailable. Analytics should diagnose UX problems, not merely demonstrate that users interacted with the interface.

UX Review

Apply to important journeys affected by the change, using existing measurement where adequate. Record evidence and any gaps; a cosmetic change does not require new events, and absent instrumentation does not justify speculative telemetry.

• Is the important journey observable end-to-end, with a defined start and actual successful outcome rather than only a UI interaction?
• Can completion, failure, abandonment, drop-off, duration, and relevant recovery states be measured with defined attempts and measurement windows?
• Are meaningful intermediate states measurable where they aid diagnosis?
• Are events based on semantic intent, states, and outcomes rather than individual controls, and would they remain meaningful after a UI refactor?
• Can related events be correlated across screens and asynchronous operations when necessary, with retries and duplicate events accounted for?
• Does every event have a known purpose, consumer, or decision it supports?
• Is collection limited to telemetry necessary to understand and improve the experience, consistent with privacy requirements?
• Have representative journeys been checked and measurement gaps identified, without claiming that rendering correctly proves UX completion?