meticulous-iterative-dev

name	meticulous-iterative-dev
description	Iterative frontend development loop using Meticulous for per-step visual validation. Use when implementing a multi-step frontend change and want to catch visual regressions and unintended side effects at each step, before the final cloud test run.
user-invocable	true

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.

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

Prerequisites

• Local dev server running (e.g. npm run dev or pnpm dev), serving the app at a known URL such as http://localhost:3000
• Authenticated with Meticulous: run meticulous auth whoami to log in via OAuth (an API token via METICULOUS_API_TOKEN or ~/.meticulous/config.json also works)
• Meticulous CLI installed and on PATH (the meticulous-cli-update skill handles this)

---

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-sessions

If 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 skill's local reference. The key fields to extract from each session in the output:

• Session ID — pass as --sessionId when simulating
• Base replay ID — the replay of this session on the base branch; pass as --baseReplayId to diff against. May be absent if the session has never been replayed on the base branch.
• Relevance — IsRelevant / IsRelevantBeta means 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:

• --sessionId and --baseReplayId from 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 debug.md):

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 meticulous-test skill.

The cloud run compares your branch against the base branch across the full golden set of sessions and reports any visual regressions.