ux-heart-metrics

What this skill does

<!-- VERSION: 1.2.0 | DATE: 2026-03-04 | SOURCE: PROJ-022-user-experience-skill/PLAN.md | PARENT: /user-experience skill | REVISION: iter2 precision fixes — evidence quality (Baymard specific citation, NPS bibliographic entry, Phase 5 dashboard citation), methodological rigor (goal adjudication guidance, signal-to-metric edge cases), internal consistency (tools/allowed-tools reconciliation, AGENTS.md section-name reference) -->

# HEART Metrics Sub-Skill

> **Version:** 1.2.0
> **Framework:** Jerry User-Experience / HEART Metrics (Google)
> **Constitutional Compliance:** Jerry Constitution v1.0
> **Parent Skill:** `/user-experience` (`skills/user-experience/SKILL.md`)
> **Project:** PROJ-022 User Experience Skill | Wave 2 (Lean UX + Measurement)

## Document Sections

| Section | Purpose |
|---------|---------|
| [Document Audience](#document-audience-triple-lens) | Triple-Lens audience guide |
| [Purpose](#purpose) | What `/ux-heart-metrics` does and key capabilities |
| [When to Use This Sub-Skill](#when-to-use-this-sub-skill) | Activation triggers, routing path, and scope boundaries |
| [Available Agents](#available-agents) | Single agent roster with role, model, and output location |
| [Invoking an Agent](#invoking-an-agent) | Three invocation methods and H-26(c) registration exception |
| [P-003 Compliance](#p-003-compliance) | Worker agent hierarchy position |
| [Methodology](#methodology) | HEART methodology adapted for AI-augmented UX measurement |
| [MCP Integration](#mcp-integration) | MCP dependencies and degraded mode behavior |
| [Output Specification](#output-specification) | Output format, location, and confidence classification |
| [Cross-Framework Integration](#cross-framework-integration) | How HEART output feeds into and receives from other sub-skills |
| [Synthesis Hypothesis Validation](#synthesis-hypothesis-validation) | Confidence gates for AI-synthesized metric recommendations |
| [Constitutional Compliance](#constitutional-compliance) | Governing principles |
| [Quick Reference](#quick-reference) | Common workflows and invocation examples |
| [References](#references) | Full repo-relative paths to all referenced files |

## Document Audience (Triple-Lens)

This SKILL.md serves multiple audiences:

| Level | Audience | Sections to Focus On |
|-------|----------|---------------------|
| **L0 (Stakeholder)** | Product managers, team leads | [Purpose](#purpose), [When to Use This Sub-Skill](#when-to-use-this-sub-skill), [Quick Reference](#quick-reference) |
| **L1 (Developer)** | Engineers invoking the sub-skill | [Methodology](#methodology), [Output Specification](#output-specification), [Available Agents](#available-agents) |
| **L2 (Architect)** | Workflow designers, skill maintainers | [Cross-Framework Integration](#cross-framework-integration), [P-003 Compliance](#p-003-compliance), [Synthesis Hypothesis Validation](#synthesis-hypothesis-validation) |

---

## Purpose

The `/ux-heart-metrics` sub-skill provides AI-augmented UX measurement using Google's HEART framework (Rodden, Hutchinson & Fu, 2010) for tiny teams (1-5 people) who need structured, dashboard-ready UX metrics without a dedicated analytics or UX research team. It guides teams through the Goals-Signals-Metrics (GSM) process to translate abstract UX goals into concrete, measurable indicators.

HEART shifts the team's thinking from "how do we know if our UX is good?" to "what specific user behaviors tell us our UX is improving?" -- enabling data-driven UX decisions even when dedicated analytics resources are limited.

### Key Capabilities

- **HEART Dimension Selection** -- Guides teams to select the subset of HEART dimensions (Happiness, Engagement, Adoption, Retention, Task Success) most relevant to their product or feature, since not all five apply to every context
- **Goals-Signals-Metrics (GSM) Process** -- Structured three-step process for each selected dimension: define the goal, identify behavioral signals, and specify measurable metrics
- **Goal Definition** -- Helps teams articulate what they are trying to improve in user-centered terms (not business metrics) for each selected HEART dimension
- **Signal Identification** -- Identifies observable user behaviors that indicate progress toward each goal, distinguishing leading and lagging indicators
- **Metric Specification** -- Produces dashboard-ready metric definitions including metric name, formula, data source, target threshold, measurement frequency, and alerting conditions
- **Baseline Establishment** -- Guides teams to establish current measurement baselines before implementing changes, enabling before/after comparison
- **Threshold Recommendation** -- Provides directional target values based on industry benchmarks or baseline measurement (LOW confidence -- requires domain-specific calibration)

### AI-Augmented Measurement Caveat

All HEART outputs from this sub-skill are synthesized from secondary research and established framework methodology rather than direct analysis of the product's actual analytics data. Synthesis outputs carry confidence levels that vary by output type:

- **Goal-metric mapping interpretation:** MEDIUM confidence -- the GSM process is methodologically grounded (Rodden, Hutchinson & Fu, 2010) but context-dependent
- **Metric threshold recommendation:** LOW confidence -- threshold values require domain-specific benchmarking data unavailable in training data

See [Synthesis Hypothesis Validation](#synthesis-hypothesis-validation) for the full confidence gate protocol.

> **Deployment status:** Wave 2 sub-skill. The agent definition (`skills/ux-heart-metrics/agents/ux-heart-analyst.md`) is currently a stub with frontmatter and core identity sections. Full implementation (complete `<methodology>`, `<input>`, `<capabilities>`, `<output>` XML-tagged body sections) is a Wave 2 deliverable of PROJ-022. The methodology documented in this SKILL.md describes the target behavior the agent will execute once fully implemented.

---

## When to Use This Sub-Skill

### Activation Path

This sub-skill is invoked by the `ux-orchestrator` agent via the `/user-experience` parent skill's lifecycle-stage routing. It is NOT invoked directly by users.

**Routing path:** User request reaches `/user-experience` via trigger keywords. The `ux-orchestrator` routes to `/ux-heart-metrics` when the user's intent matches:

| Stage Category | User Intent | Route |
|---------------|-------------|-------|
| After launch | "Measure UX health" | `/ux-heart-metrics` |
| Any stage | "Measure whether UX is working" | `/ux-heart-metrics` |
| Any stage | Comprehensive UX audit (multi-sub-skill) | `/ux-heuristic-eval` then `/ux-heart-metrics` |
| CRISIS | Urgent UX problems (step 3 of 3-skill sequence) | `/ux-heart-metrics` |

Source: `skills/user-experience/rules/ux-routing-rules.md` [Stage Routing Table].

### Trigger Keywords

| Keyword | Specificity |
|---------|------------|
| HEART | Primary |
| metrics | Primary |
| GSM | Primary |
| goals signals metrics | Primary |
| UX metrics | Primary |
| measurement | Primary |
| dashboard | Secondary |
| happiness | Secondary |
| engagement | Secondary |
| adoption | Secondary |
| retention | Secondary |
| task success | Secondary |
| baseline | Secondary |
| metric threshold | Secondary |

### Do NOT Use When

| Condition | Use Instead | Why |
|-----------|-------------|-----|
| Understanding what users want to accomplish | `/ux-jtbd` | JTBD discovers underlying jobs; HEART measures outcomes of addressing those jobs |
| Evaluating an existing design against usability standards | `/ux-heuristic-eval` | Heuristic evaluation assesses design quality against Nielsen's 10; HEART measures user behavior |
| Testing and iterating on a hypothesis | `/ux-lean-ux` | Lean UX manages the experiment cycle; HEART measures the outcome |
| Diagnosing why users fail to complete an action | `/ux-behavior-design` | Behavior design (Fogg B=MAP) diagnoses bottlenecks; HEART measures whether