Consolidate repository skills under .agents/skills

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

@@ -0,0 +1,101 @@
+---
+name: ux-observability
+description: 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?