meticulous-simulate-and-diff

A workflow for running a single Meticulous session simulation against a live URL and interpreting the visual result, used to check whether a code change has introduced a visual regression for a specific recorded session. It runs in two modes: diff mode, which compares pixel and HTML diffs against a prior base replay, and quick-check mode, which omits the base replay and simply stores screenshots for direct visual inspection.

Operationally it invokes the meticulous simulate CLI with a sessionId, an appUrl (a local dev server, or left blank to reuse the originally recorded URL), an optional baseReplayId, and --headless, then reads the stdout. Per-screenshot lines report the pixel-mismatch percentage against a threshold with a PASS or FAIL outcome, and a summary block prints the simulation URL plus a base-to-head comparison URL. If there are no FAIL lines, the session is visually identical to the base and no further analysis is needed.

When diffs exist, it locates the head replay directory under ~/.meticulous/replays/, identifies the changed screenshots in diffs/<baseReplayId>/, and reads each screenshot's metadata.json to compare the before.dom HTML snapshot and before.routeData.url. This distinguishes structural changes (DOM additions or removals) from purely visual ones (a pixel shift with identical DOM), and maps changed CSS classes and routes back to the responsible components. The final output is a high-level, human-readable description of what changed and why, with the comparison URL surfaced for quick human verification. It references companion skills meticulous-cli-simulate, meticulous-cli-update, and meticulous-iterative-dev.