vrt

Visual Regression Triage

When a Playwright visual regression test fails, present the baseline, actual, and diff images alongside the user's current task context, then guide the user to either fix the underlying bug or update the baseline.

Configuration (optional)

Reads .local/repos.json (walked up from pwd) to look up the GitHub owner/repo for the current project so that gh issue view can fetch task context. If .local/repos.json is missing or the current project isn't found, the skill falls back to whatever gh is configured to use.

{
  "<name>": {
    "path": "<absolute repo path matching pwd>",
    "github": {"owner": "...", "repo": "..."}
  }
}

The skill identifies the current project by matching pwd (or its parent) to an entry's path value; the matching entry's key is <name>.

A skill-specific config file .claude/visual-regression.config.json is supported but optional:

{
  "test_command":            "pnpm test:e2e --project=visual-regression",
  "update_command":          "pnpm test:e2e --project=visual-regression --update-snapshots",
  "results_glob":            "test-results/**/*-actual.png",
  "snapshot_naming": {
    "actual_suffix":   "-actual.png",
    "expected_suffix": "-expected.png",
    "diff_suffix":     "-diff.png"
  }
}

If the config is missing, defaults match Playwright's standard layout and use a generic npx playwright test invocation.

Process

1. Gather task context

Before examining images, understand what the user is working on:

1. git branch --show-current — current branch.
2. git log --oneline -5 — recent commits; look for issue numbers and Conventional Commit types.
3. If commits or branch name reference an issue number #N, look up the issue:

   OWNER=$(jq -r --arg n "$NAME" '.[$n].github.owner // empty' .local/repos.json)  # $NAME = matched key
   REPO=$(jq -r --arg n "$NAME" '.[$n].github.repo // empty' .local/repos.json)
   gh issue view "$N" --repo "$OWNER/$REPO" --json title,body
   

   If OWNER/REPO are unavailable, run gh issue view "$N" with no --repo flag.
4. git diff --name-only HEAD~5 — recently changed files.