/triaging-visual-review-runs

name: triaging-visual-review-runs
description: >
  Inspects PostHog Visual Review (VR) runs that gate PR merges with screenshot regression checks.
  Use when the user mentions "visual review", "VR", "snapshot diff", "screenshot test", "storybook regression",
  "playwright snapshot", asks why a PR is blocked or what changed visually, wants to triage the VR backlog,
  decide whether a snapshot diff is real vs flaky, or check whether a story has been changing across runs.
  Also invoke when a PR has a failing `visual-review` status check, when a PR comment mentions "Visual review",
  or when the user is on a branch with an open VR run.

Triaging visual review runs

Visual Review is PostHog's screenshot-regression product: CI captures storybook + playwright screenshots, diffs them against committed baseline hashes, and gates the PR until a human approves the visible changes. A PR with visual changes carries a `visual-review` GitHub status check that stays red until each diffed snapshot is approved or tolerated in the [VR UI](https://us.posthog.com/project/2/visual_review).

This skill teaches an agent how to answer the questions a human reviewer would actually ask, by chaining the VR MCP tools — instead of reaching for `gh pr view` and tab-hopping to the VR web UI. The read tools cover status / scope / history / triage. Two are reversible DB-only triage marks (`approve-create`, `tolerate-create`); one ships the change (`finalize-create`) — it commits the baseline and greens the gate, and only that one needs explicit per-run human confirmation.

When this skill applies

Trigger this skill on any of:

• A PR number, branch name, or commit SHA paired with words like _visual review_, _VR_, _snapshot_, _screenshot_,

_storybook diff_, _playwright snapshot_, _baseline_, _approve_, _tolerated_, _quarantine_.

• Questions about why a PR is blocked, what visually changed, or whether a diff is real.
• "Is my run done?" / "What's left to review?" / "Has this story flaked recently?"
• A failing `visual-review` GitHub check or a PR comment from the `posthog-bot` mentioning visual review.

When the user asks for the rendered diff image itself, the [VR web UI](https://us.posthog.com/project/2/visual_review) is faster — direct them there. This skill is for everything around the diff: status, scope, history, triage.

Tools

Read tools (safe to call freely):

| Tool | Purpose | | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `posthog:visual-review-runs-list` | List runs, filter by `pr_number` / `commit_sha` / `branch` / `review_state`. Start here. | | `posthog:visual-review-runs-retrieve` | Full detail for a single run (status, summary counts, supersession). | | `posthog:visual-review-runs-snapshots-list` | Per-snapshot results inside a run: identifier, `result`, diff %, classification, baseline + current artifact URLs. Quarantined snapshots are excluded by default (see `quarantined_count`); pass `include_quarantined=true` to see them. | | `posthog:visual-review-runs-snapshot-history-list` | A single story's last N runs across master/PRs — the flake check. | | `posthog:visual-review-runs-counts-retrieve` | Aggregate counts for queue triage (how many runs in `needs_review`, etc.). | | `posthog:visual-review-runs-tolerated-hashes-list` | Hashes the team has explicitly accepted as "known flake / acceptable variation". | | `posthog:visual-review-repos-list` | Repos (one per GitHub repo) — usually only one matters; useful for filtering. | | `posthog:visual-review-repos-retrieve` | Repo metadata: baseline file paths, PR-comment configuration. |

Triage tools (reversible, DB-only — they record a review decision but do NOT change the baseline or the gate):

| Tool | Purpose | | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | `posthog:visual-review-runs-approve-create` | Mark `changed` / `new` snapshots reviewed (approved) in the DB. Does NOT commit or green the gate — ship via finalize. | | `posthog:visual-review-runs-tolerate-create` | Mark a single changed snapshot a