Clarity Session Review — Development skill for Claude Code

clarity-session-review

A reusable agent **skill** for reviewing [Microsoft Clarity](https://clarity.microsoft.com) session recordings the way that produces **findings, not anecdotes** — and doesn't let a half-trusted event timeline become a confident, wrong story.

It's a discipline, not a dashboard: question-scoped triage → attribution → replay-watch → database/source triangulation → a verifiable evidence appendix. It runs as a [Claude Code](https://claude.com/claude-code) / Codex skill (a `SKILL.md` the agent loads on demand), but the method reads fine as a plain playbook for a human, too.

Why it exists

It was born the day replay-watching **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;
• a dramatic "48-minute struggle session" was an internal teammate's own browser.

Every one was read straight off the Clarity event timeline. Watching the replays — and checking them against the product database and the frontend source — reversed all four. This skill is the checklist that makes that the default, not the lucky exception.

The eight principles (each one paid for by a specific mistake)

1. Question before player. No discriminating question → no watching.
2. Attribute before interpreting. Wire Clarity's Identify API if you can — it's the first-class join. Until then, session-entry URLs usually carry the identity — join it to your database before you interpret anything.
3. A replay alone is a story; replay + database + source code is a finding. Triangulate every load-bearing claim.
4. TIMELINE ≠ REPLAY. API timelines are truncated and masked — treat their counts as floors; never present a timeline read as watched.
5. Every claim ships with its evidence coordinates — link + timestamps + what t