Iterative Frontend Development with Meticulous
Use this skill when implementing a multi-step frontend change. After each step, run a quick local visual check using Meticulous to catch regressions and unintended side effects early. After all steps are complete, run a full cloud test run to validate across all recorded sessions.
Prerequisites
- Local dev server running (e.g.
npm run devorpnpm dev), serving the app at a known URL such ashttp://localhost:3000 - API token configured:
~/.meticulous/config.jsonorMETICULOUS_API_TOKENenvironment variable - Meticulous CLI available:
npx @alwaysmeticulous/cliormeticulousif installed globally
Per-step loop
Repeat the following for each step of your change.
Step 1 — Implement the step's changes
Make your code changes for this step.
Step 2 — Find relevant sessions
Run:
meticulous local relevant-sessionsIf you have already committed previous steps and want to find sessions relevant only to this step's uncommitted changes, pass the SHA of the last commit:
meticulous local relevant-sessions --startingPointSha=<sha-of-last-commit>For full option reference see the meticulous-cli-local skill. The key fields to extract from each session in the output:
- Session ID — pass as
--sessionIdwhen simulating - Base replay ID — the replay of this session on the base branch; pass as
--baseReplayIdto diff against. May be absent if the session has never been replayed on the base branch. - Relevance —
IsRelevant/IsRelevantBetameans the session directly exercises changed code.
If no sessions are returned, the changed code is not covered by any recorded session. Proceed to Step 4 (commit) and rely on the final cloud run for coverage.
Step 3 — Simulate and analyse
Pick 1–2 of the most relevant sessions (prefer IsRelevant over IsRelevantBeta). For each, follow the meticulous-simulate-and-diff skill using:
--sessionIdand--baseReplayIdfrom step 2's output--appUrl=http://localhost:<port>pointing at your local dev server--headless(required — agents should not operate a visible browser)
If baseReplayId was absent from the output, omit it; use quick-check mode from that skill instead.
Also consider simulating a session for an unexpected flow surfaced by local relevant-sessions — one that covers code you didn't intend to change — to check for unintended side effects.
Once you have the analysis, classify each visual difference:
- Expected — a direct, intended consequence of this step's changes. Proceed.
- Unexpected — a visual change that was not a goal of this step (including side effects of your code, even if explainable). Investigate.
If unexpected and the cause is clear: fix the code and re-simulate.
If the cause is unclear: create a self-contained AI-readable debug workspace using the replay IDs from the simulation output URL (see the meticulous-cli-debug skill):
meticulous debug replay <headReplayId> --baseReplayId=<baseReplayId>Both IDs come from the simulation output URL: the head replay ID is the last path segment of the View simulation at: URL; the base replay ID is the --baseReplayId used in the simulate command. Open the workspace to diagnose, fix, and re-simulate.
Step 4 — Commit
Once the step's visual output is correct, commit your changes:
git add -p
git commit -m "<concise description of this step>"Committing after each step means the next iteration's --startingPointSha call computes the diff relative to this checkpoint, preventing prior steps' changes from inflating the set of relevant sessions.
Return to Step 1 for the next step.
After all steps — full cloud test run
Once all steps are complete and committed, run a full cloud test run to validate across all recorded sessions (not just the 1–2 you simulated locally):
Follow the test-with-meticulous skill.The cloud run compares your branch against the base branch across the full golden set of sessions and reports any visual regressions.