Review session recordings with evidence-based findings

clarity-session-review is a discipline for reviewing Microsoft Clarity session recordings that produces findings, not anecdotes, structured as question-scoped triage, attribution, replay-watch, database and source triangulation, and a verifiable evidence appendix. It runs as a Claude Code/Codex skill, a SKILL.md the agent loads on demand, but reads as a plain playbook for a human too. It exists because replay-watching once overturned four timeline-based conclusions in a single investigation: a user filed as "bailed at the redirect" had actually spent two minutes inside the hosted OAuth flow; a "five-day starer" was a hidden background tab; a "never-returned" user had returned; and a dramatic "48-minute struggle session" was an internal teammate's own browser - all four were read straight off the Clarity event timeline, and only reversed once checked against replays, the product database, and the frontend source. The skill encodes seven principles, each attributed to a specific mistake that paid for it: question before player, since no discriminating question means no watching; attribute before interpreting, since Clarity has no identify() so session-entry URLs usually carry identity and must be joined to the database before interpretation; a replay alone is a story, replay plus database plus source code is a finding, so every load-bearing claim gets triangulated; TIMELINE does not equal REPLAY, since API timelines are truncated and masked so their counts are floors and a timeline read must never be presented as watched; every claim ships with its evidence coordinates - link, timestamps, and what to check - so verification is a two-minute job; count people, not sessions, since Clarity fragments one visit into many sessions (one user showed up as 59) and 50-60% of a pull is thin bounces, so a run of 462 sessions turned out to be about 26 real people, and that's the number to lead with; and audit what the UI shows, not only what users click, since the method is behavioral and blind to a misleading label or a dead-end status, requiring a source-lint of the label code to catch those, marked provisional.

Use it in two modes: targeted investigation for a specific question such as "why did user X churn," "verify the fix," or "what did this user do before the call," run directly through the pipeline, or periodic census, the recurring session-intelligence report over every session in a window, orchestrated as a resumable multi-agent workflow - scout, triage fan-out, serial watch, synthesize plus adversarial refute. The skill auto-loads when asked to "watch recordings," "check Clarity," "review all sessions," "why did users drop off," "verify the fix," or "run the dead-click review." It is explicitly not a Clarity API wrapper or scraper - it's the judgment layer on top of Clarity's own tools (MCP, API, dashboard) - and it is not a substitute for analytics; it's the replay discipline that explains what aggregate numbers can't, and names what the instrument is blind to.

Five files make up the skill: SKILL.md itself, covering the seven principles, the two modes, the pipeline, the report contract, a replay-semantics gotcha list, cadences, and blind spots; references/method.md for per-session mechanics and standing modules, including a Clarity-instruments toolkit noting recordings are just one of roughly ten instrument families, thin-session forensics, dead-click analysis with a verify-first gate since a dead-click count is not a defect count, and a UI-clarity review; references/periodic-review.md for the Mode B recurring report workflow; ADAPTING.md, an eight-item checklist for wiring the method to a specific product, such as the URL-to-identity join, the product's own database, its exclusion list, and its source paths; and examples/, a templatized, data-driven report generator. Output is a findings report where every claim carries evidence coordinates - a link, timestamps, and what to check - rather than a narrative summary.

Sits on top of Microsoft Clarity's own tooling (MCP, API, dashboard) as a judgment layer rather than replacing or wrapping it; installed by cloning the repo and symlinking it into an agent's skills directory, for example ln -s "$PWD" ~/.claude/skills/clarity-session-review for Claude Code, so updates propagate automatically.

Anyone using Microsoft Clarity session recordings to investigate a specific user behavior or run a recurring session-intelligence report, who wants a checklist that defaults to triangulated findings instead of a confident, wrong story read straight off an event timeline. It is MIT licensed, distilled from real practice, with battle-tested principles and anonymized examples.