Meticulous Review

To review a Meticulous test run, follow the workflow below step by step, using the CLI or MCP commands as described.

Before starting, run the meticulous-cli-update skill to ensure the Meticulous CLI and skills are up to date — unless it has already run earlier in this conversation, in which case skip it.

This skill treats you as a reviewer, not the implementer — even if you did write the change earlier in this conversation. Its job is to catch regressions, not to iterate on the implementation (if you're mid-implementation and want to loop against Meticulous until things look right, see the meticulous-iterative-dev skill for feature work with intended visual changes, or the meticulous-zero-diff-task skill when the UI must not change; if diffs have already been reviewed and rejected and you're just here to fix what's flagged, see the meticulous-fix skill).

Step 0 -- Establish what's expected

Before looking at any diff, work out what visual change this PR is supposed to produce:

• If you already have full context (same conversation that implemented the change, or the user just described the task), use that.
• Otherwise — fetch the PR description (e.g. gh pr view <number> --json title,body for GitHub, glab mr view <id> --output json --jq '{title,description}' for GitLab, or GET /2.0/repositories/{workspace}/{repo_slug}/pullrequests/{id}?fields=title,description for Bitbucket) and pull out a brief bullet-point summary of any visual changes it calls out as expected.
• If it doesn't mention any, note that explicitly — every diff below then gets extra scrutiny, since there's nothing on record it could be a known, accepted consequence of.

Step 1 -- Get the replay diff summary

Run from the local checkout to resolve the test run from the current commit's git HEAD — make sure HEAD matches the remote head CI ran on first (e.g. git pull), or you may review a stale or missing run:

# CLI (infers the run from local git HEAD)
meticulous agent test-run-diffs

# MCP (git context is never inferred — resolve the testRunId from a commit first)
get_test_run_for_commit(commitSha="<sha>")
get_test_run_diffs(testRunId="<id>")

Returns a TSV of replayDiffId/screenshotName rows — a representative, priority-ordered subset of real visual differences; work through them top to bottom. To target a run explicitly instead of resolving from HEAD, pass --testRunId <id> or --commitSha <sha>. The CLI blocks until the run finishes by default (pass --dontWaitForTestRunToComplete to instead report an in-progress run and exit immediately); MCP never blocks, so keep polling until status is complete/failed.

Every returned row must be matched against Step 0 or flagged (see the Decision guide) before concluding the PR is good.

Step 2 -- Get screenshot images

For each representative screenshot:

# CLI (downloads images to ~/.meticulous/agent-images/ and prints local paths)
meticulous agent image-files --replayDiffId <replayDiffId> --screenshotName <screenshotName>

# MCP (no download-to-disk tool — returns signed URLs instead; fetch them to view the images)
get_image_urls(replayDiffId="<replayDiffId>", screenshotName="<screenshotName>")

Open (or fetch) before, after, and diffImage to inspect the change — diffImage is usually the most informative, highlighting exactly which pixels changed. Always inspect the images, even when the DOM diff looks clear.

Step 3 -- Inspect the DOM diff (for structural detail)

# CLI
meticulous agent dom-diff --replayDiffId <replayDiffId> --screenshotName <screenshotName>

# MCP
get_dom_diff(replayDiffId="<replayDiffId>", screenshotName="<screenshotName>")

Optional: --context <N|full> (CLI) controls how many context lines surround each hunk (default 3).

Output is a unified diff (+/-, indentation stripped), one [diff N]-headed block per independent change — for example (illustrative, not real output):

[diff 0]
 <div class="item">
-  <span class="label">old label</span>
+  <span class="label" data-flag="true">new label</span>
 </div>
[diff 1]
 <ul class="list">
+  <li>new item</li>
 </ul>

Step 4 -- Get the replay timeline (optional, for diagnosing unexpected diffs)

If a diff is unexpected and the images/DOM don't make it obvious why:

# CLI
meticulous agent timeline-diff --replayDiffId <replayDiffId>

# MCP
get_timeline_diff(replayDiffId="<replayDiffId>")

TSV columns: diff ( identical, - removed, + added, ! changed), timeMs, event (user/screenshot/network/console/etc.), description. Look for failed network requests, unexpected redirects, or timing anomalies that could explain a visual change.