/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", "quarantine", 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, quarantine or lift a flaky story, 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",
  when a PR from a fork fails a screenshot check, 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 every changed snapshot is resolved. A PR with visual changes carries a `visual-review` GitHub status check, and usually a required CI job that reports the same verdict. Both stay red until each diffed snapshot is approved and finalized, tolerated, or quarantined, and the job re-runs: finalize does that for approvals, `recompute-create` for tolerations and quarantines. The run's `_posthogUrl` opens the VR UI, which offers the same actions. A PR from a fork is usually the exception: it gets no Visual Review run at all. See [Fork PRs have no Visual Review run](#fork-prs-have-no-visual-review-run).

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. An agent may resolve flakes on its own, with a quarantine or, rarely, a toleration. It may not ship a visual change on its own: `finalize-create` commits the baseline and needs explicit per-run human confirmation.

Decide first

Gather the evidence with [Is the diff real or unrelated?](#is-the-diff-real-or-unrelated) and the [flake check](#flake-check-has-this-story-been-changing), then take the first row that matches each changed snapshot.

| Evidence | Action | Human yes needed | | ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | | PR comes from a fork (`isCrossRepository: true`) | Report only. See [Fork PRs](#fork-prs-have-no-visual-review-run) | No VR writes possible | | The diff comes from your change and is intended | `approve-create`, then ask for finalize | Yes, for each run, before finalize | | The diff comes from your change and is not intended | Fix the code and push. No VR write | No | | Your change renders a quarantined story `changed` or `new`, and the change is intended | `approve-create` for that identifier, then ask for finalize. If the change also fixes the flake, add `lift-on-merge-create` after the approval. See [Quarantined stories](#quarantined-stories-in-your-run) | Yes, for each run, before finalize | | Your change fixes a quarantined story's flake, and the story renders `unchanged` | `lift-on-merge-create` for that identifier. See [Quarantined stories](#quarantined-stories-in-your-run) | No | | Story outside your change, flakiness entry `unstable`, `hard_count` ≥ 5, `last_flaked_at` in the last 7 days | `quarantine-create`, then `recompute-create`. Report it | No | | Story outside your change, flakiness entry `broken` | Do not quarantine. Its baseline on the default branch is wrong. Report it and recommend a re-baseline | Yes | | Story outside your change, quiet history, same width and height, `change_kind: pixel`, a noise source you can name | `tolerate-create`, then `recompute-create` | No | | Anything else: `unstable` with fewer failures, a real-looking change you did not make, unsure | Stop a