Back to Details

meticulous-zero-diff-task

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
To grind out a no-diff (or low-diff) implementation task, 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 is for tasks whose success criterion is visual stability, not visual change: dependency/version upgrades, refactors, migrations (e.g. framework/library swaps, build-tool changes), and similar work where any Meticulous diff is a sign something broke, not a feature to explain away. It also works for low-diff tasks (a handful of expected, well-understood visual changes alongside mostly-unchanged output) — the loop is the same, just with a smaller set of diffs you expect to end up justifying rather than fixing.
要完成无差异（或低差异）的实现任务，请按照以下步骤逐步操作，使用下文所述的CLI或MCP命令。
开始前，请运行
meticulous-cli-update
技能以确保Meticulous CLI及相关技能为最新版本——如果本次对话中之前已经运行过，则可跳过此步骤。
本技能适用于以视觉稳定性为成功标准的任务，而非需要视觉变更的任务：包括依赖/版本升级、重构、迁移（例如框架/库替换、构建工具变更）等工作，这类任务中任何Meticulous检测出的差异都意味着出现了问题，而非需要解释的新特性。它同样适用于低差异任务（除少量可预期、已明确的视觉变更外，大部分输出保持不变）——流程完全相同，只是最终需要说明的差异数量更少，而非修复这些差异。

Step 1 -- Implement the task

Step 1 -- 实现任务

Make the code change described by the task (the upgrade, refactor, or migration). Commit as you go if the task naturally breaks into steps — this isn't specific to Meticulous, just do the implementation work.
完成任务要求的代码变更（升级、重构或迁移）。如果任务自然可拆分为多个步骤，可随时提交代码——这并非Meticulous特有的要求，只需正常完成实现工作即可。

Step 2 -- Build the frontend

Step 2 -- 构建前端

  1. Find out what build artefact Meticulous expects by checking 
    .github/workflows/
    for one of the following steps: 
    • uses: alwaysmeticulous/report-diffs-action/upload-assets@v1
      — build assets
    • uses: alwaysmeticulous/report-diffs-action/upload-container@v1
      — docker image
  2. Build the frontend following the same instructions as used in the GitHub workflow.
  1. 通过查看
    .github/workflows/
    中的以下步骤，确认Meticulous期望的构建产物类型： 
    • uses: alwaysmeticulous/report-diffs-action/upload-assets@v1
      —— 构建资源文件
    • uses: alwaysmeticulous/report-diffs-action/upload-container@v1
      —— Docker镜像
  2. 按照GitHub工作流中使用的相同指令构建前端。

Step 3 -- Upload the build and trigger a test run

Step 3 -- 上传构建产物并触发测试运行

bash
undefined
bash
undefined

CLI

CLI

meticulous agent upload-build --appDirectory <path-to-build> # assets meticulous agent upload-build --localImageTag <image-tag> # container meticulous agent trigger-test-run --deploymentId <deploymentId>
meticulous agent upload-build --appDirectory <path-to-build> # 资源文件 meticulous agent upload-build --localImageTag <image-tag> # 容器 meticulous agent trigger-test-run --deploymentId <deploymentId>

MCP (upload is not 1:1 — request an upload URL, upload the artifact yourself, then register it)

MCP（上传操作并非一一对应——需先请求上传URL，自行上传产物，然后完成注册）

request_asset_upload(size=<zipByteSize>) # or request_container_upload() — no required args
request_asset_upload(size=<zipByteSize>) # 或request_container_upload() —— 无必填参数

... upload the zip/image to the returned URL/registry yourself ...

... 自行将压缩包/镜像上传至返回的URL/镜像仓库 ...

register_asset_build(uploadId="<id>", commitSha="<sha>") # or register_container_build(uploadId="<id>", commitSha="<sha>") trigger_test_run(deploymentId="<deploymentId>", baseSha="<sha>")

`trigger_test_run` on MCP never infers `baseSha`/`gitDiffOutput` (compute the base locally) and always returns immediately without waiting for the run to finish (unlike the CLI, which blocks by default).

Run `trigger-test-run` from the repo directory to infer both the base (merge-base with the origin default branch) and the git diff automatically. See the `meticulous-cli` reference for the full option list — in particular, the working tree can be dirty (captured as an ephemeral commit) so you don't need to commit before each iteration below.

Note the `testRunId` from the output.
register_asset_build(uploadId="<id>", commitSha="<sha>") # 或register_container_build(uploadId="<id>", commitSha="<sha>") trigger_test_run(deploymentId="<deploymentId>", baseSha="<sha>")

MCP中的`trigger_test_run`永远不会自动推断`baseSha`/`gitDiffOutput`（需在本地计算基准版本），且始终立即返回，不会等待运行完成（与默认会阻塞的CLI不同）。

从仓库目录运行`trigger-test-run`可自动推断基准版本（与远程默认分支的合并基准）和Git差异。查看`meticulous-cli`参考文档获取完整选项列表——特别注意，工作树可以是脏状态（会被捕获为临时提交），因此在以下每次迭代前无需提交代码。

记录输出中的`testRunId`。

Step 4 -- Check for diffs, and iterate until clean

Step 4 -- 检查差异，迭代至无差异状态

Inspect the diffs using the mechanics from the 
meticulous-review
skill (Steps 1-4 there: 
agent test-run-diffs
, screenshot images, DOM diff, timeline) — but apply this decision rule instead of the 
meticulous-review
skill's expected-vs-regression framework:
For a no-diff task, treat every returned diff as a bug until proven otherwise. The premise of this skill is that the UI shouldn't change, so:
  1. No diffs at all — you're done with this step; proceed to Step 5.
  2. One or more diffs — for each one, look at the screenshot images and DOM diff (as in the 
    meticulous-review
    skill's Steps 2-3) to understand exactly what changed and why, using the timeline (Step 4 there) if the cause isn't obvious from the DOM/images alone. Then classify it:
    • Regression (the default assumption) — a real side effect of your change.
    • Acceptable — you can positively explain it as an intended, unavoidable consequence of the task itself (e.g. a version-string footer changing as part of a version upgrade). Be conservative here — for a low-diff task there may genuinely be a handful of these; for a strict no-diff task there normally shouldn't be any. Don't reject or ignore these yet — hold off until Step 6, where the verdict gets filed against the PR's own CI-triggered run rather than a provisional local iteration.
    • Can't fix, and can't confidently justify either — don't get stuck looping over it.
For a regression, reject it right away so there's a paper trail as you go — even though you're both reviewer and implementer here:
bash
undefined
使用
meticulous-review
技能中的方法（其中的步骤1-4：
agent test-run-diffs
、截图、DOM差异、时间线）检查差异——但需遵循以下决策规则，而非
meticulous-review
技能中的“预期变更vs回归”框架：
对于无差异任务，除非能证明并非问题，否则将所有返回的差异视为Bug。 本技能的核心前提是UI不应发生变化，因此：
  1. 完全无差异 —— 此步骤完成；进入Step 5。
  2. 存在一个或多个差异 —— 针对每个差异，查看截图和DOM差异（如
    meticulous-review
    技能的步骤2-3所述），准确了解变更内容及原因；如果仅从DOM/截图无法明确原因，可使用时间线（其中的步骤4）。然后对差异进行分类：
    • 回归（默认假设） —— 变更带来的真实副作用。
    • 可接受 —— 可明确解释为任务本身预期且不可避免的结果（例如版本升级时页脚的版本字符串变更）。此处需保持谨慎——低差异任务中可能确实存在少量此类差异；而严格的无差异任务通常不应存在此类差异。暂时不要拒绝或忽略这些差异——等到Step 6，再针对PR自身CI触发的运行记录结论，而非本地临时迭代的结果。
    • 无法修复，且无法明确说明合理性 —— 不要在此处陷入循环。
对于回归差异，立即拒绝并留下记录——即使你同时是审核者和实现者：
bash
undefined

CLI

CLI

meticulous agent reject-diff --replayDiffId=<id> --screenshotName=<name> --reason="<what broke>" --x=<0..1> --y=<0..1>
meticulous agent reject-diff --replayDiffId=<id> --screenshotName=<name> --reason="<what broke>" --x=<0..1> --y=<0..1>

MCP

MCP

reject_diff(replayDiffId="<id>", screenshotName="<name>", reason="<what broke>", x=<0..1>, y=<0..1>)

Then fix the code so the behavior/output matches the pre-change baseline, and go back to Step 3 to rebuild and re-run (new build, same base). Once a later run confirms that diff no longer reproduces, close the loop by replying "Fixed" to the comment thread — pass the `id` `reject-diff` returned as `--commentId`:

```bash
reject_diff(replayDiffId="<id>", screenshotName="<name>", reason="<what broke>", x=<0..1>, y=<0..1>)

然后修复代码，使其行为/输出与变更前的基准版本一致，回到Step 3重新构建并运行（新的构建产物，相同的基准版本）。当后续运行确认该差异不再出现时，通过回复“Fixed”关闭该循环——将`reject-diff`返回的`id`作为`--commentId`传入：

```bash

CLI

CLI

meticulous agent reply-to-diff-comment --commentId=<id> --text="Fixed."
meticulous agent reply-to-diff-comment --commentId=<id> --text="Fixed."

MCP

MCP

reply_to_diff_comment(commentId="<id>", text="Fixed.")

A diff you can't fix and can't confidently justify gets rejected the same way, with a reason explaining what's blocking you so the thread reflects reality — but leave it unresolved (no "Fixed" reply), and call it out clearly and specifically in the final report and in the PR description (Step 5) so a human can make the call.

Repeat Steps 3-4 until either no diffs remain, or every remaining diff is justified or explicitly flagged as unresolved.
reply_to_diff_comment(commentId="<id>", text="Fixed.")

对于无法修复且无法明确说明合理性的差异，同样以相同方式拒绝，说明阻碍你的原因，让线程记录真实情况——但不要标记为已解决（不回复“Fixed”），并在最终报告和PR描述（Step 5）中明确指出，由人工做出决策。

重复Step 3-4，直到完全无差异，或所有剩余差异均已说明合理性或被明确标记为未解决。

Step 5 -- Create the PR

Step 5 -- 创建PR

Once the run is clean (or every remaining diff is accounted for), commit any outstanding changes, push the branch, and open the PR.
In the PR description:
  • Summarize the task and, briefly, the Meticulous result: e.g. "Verified via Meticulous: no visual differences across the golden set" or, if some diffs remain, a short list of what they are and why they're expected/unavoidable — link each one: 
    https://app.meticulous.ai/test-runs/<testRunId>/replay-diff/<replayDiffId>?screenshot=<screenshotName>
    .
  • Author credit: if the PR description already credits an AI coding assistant as (co-)author (e.g. "Created by Claude Code", "Co-authored-by: Cursor", "🤖 Generated with Claude Code"), add "and Meticulous" to that mention — e.g. "Created by Claude Code and Meticulous" — since Meticulous drove the implementation loop, not just a final check. Don't add a Meticulous author credit if no such line already exists; there's nothing to append it to.
当运行结果为无差异（或所有剩余差异均已明确）时，提交所有未提交的变更，推送分支并创建PR。
在PR描述中：
  • 总结任务内容及Meticulous的验证结果：例如“通过Meticulous验证：黄金测试集无视觉差异”；如果存在剩余差异，简要列出差异内容及预期/不可避免的原因——并为每个差异添加链接：
    https://app.meticulous.ai/test-runs/<testRunId>/replay-diff/<replayDiffId>?screenshot=<screenshotName>
    。
  • 作者署名：如果PR描述已将AI编码助手列为（共同）作者（例如“Created by Claude Code”、“Co-authored-by: Cursor”、“🤖 Generated with Claude Code”），请在该提及后添加“and Meticulous”——例如“Created by Claude Code and Meticulous”——因为Meticulous驱动了整个实现循环，而非仅作为最终检查工具。如果PR描述中没有此类署名，则无需添加Meticulous的作者署名。

Step 6 -- Confirm the PR's own test run matches

Step 6 -- 确认PR自身的测试运行结果一致

Once CI has triggered its own Meticulous test run for the pushed commit, confirm it shows the same result you already validated locally — this catches drift between your local build and CI's build (e.g. a dependency lockfile mismatch, an env var only set in CI).
bash
undefined
当CI为推送的提交触发了自身的Meticulous测试运行后，确认其结果与你本地验证的结果一致——这可以捕获本地构建与CI构建之间的差异（例如依赖锁文件不匹配、仅在CI中设置的环境变量）。
bash
undefined

CLI (resolves from local git HEAD — already the pushed commit)

CLI（从本地Git HEAD解析——已为推送的提交）

meticulous agent test-run-diffs
meticulous agent test-run-diffs

MCP (git context is never inferred — resolve the testRunId from the local HEAD commit first)

MCP（永远不会自动推断Git上下文——需先从本地HEAD提交解析testRunId）

get_test_run_for_commit(commitSha="<sha>") get_test_run_diffs(testRunId="<id>")

If CI hasn't triggered the run yet, wait and retry rather than re-triggering it yourself — the PR's run should come from the same CI pipeline a human reviewer will see. If the PR run shows different diffs than your local iteration did, treat that as a new signal: go back to Step 4 using the PR's `testRunId`.

For every diff that's still present here and that you justified rather than fixed (Step 4), leave your reasoning on the record via `ignore-diff` — this is the run CI and a human reviewer will actually see, so it's where that verdict needs to be filed:

```bash
get_test_run_for_commit(commitSha="<sha>") get_test_run_diffs(testRunId="<id>")

如果CI尚未触发运行，请等待并重试，不要自行重新触发——PR的运行应来自人工审核者会看到的同一CI流水线。如果PR的运行结果与本地迭代的差异不同，将其视为新信号：使用PR的`testRunId`回到Step 4。

对于此处仍存在且你已说明合理性（而非修复）的每个差异（Step 4），通过`ignore-diff`记录你的理由——这是CI和人工审核者实际会看到的运行，因此需要在此处记录结论：

```bash

CLI

CLI

meticulous agent ignore-diff --replayDiffId=<id> --screenshotName=<name> --reason="<why it's justified>" --x=<0..1> --y=<0..1>
meticulous agent ignore-diff --replayDiffId=<id> --screenshotName=<name> --reason="<why it's justified>" --x=<0..1> --y=<0..1>

MCP

MCP

ignore_diff(replayDiffId="<id>", screenshotName="<name>", reason="<why it's justified>", x=<0..1>, y=<0..1>)

`ignore-diff` decides nothing — the diff stays `unreviewed` and the check stays pending — but it puts your reasoning on record so the human reviewing the PR doesn't have to re-derive it.
ignore_diff(replayDiffId="<id>", screenshotName="<name>", reason="<why it's justified>", x=<0..1>, y=<0..1>)

`ignore-diff`不会做出任何决策——差异仍会保持“未审核”状态，检查仍会处于待处理状态——但它会记录你的理由，避免PR的人工审核者重新推导这些内容。

Step 7 -- Report feedback to Meticulous

Step 7 -- 向Meticulous反馈

As the last step, submit one brief feedback note to the Meticulous team: did the iterate-to-clean loop work well for this kind of task, was anything confusing, and what would have made it easier?
bash
undefined
最后一步，向Meticulous团队提交简短的反馈：这种“迭代至无差异”的流程是否适用于此类任务，是否存在混淆点，以及哪些改进会让流程更便捷？
bash
undefined

CLI

CLI

meticulous agent submit-feedback --message="<one or two sentences>" --outcome=<helped|neutral|hindered> --testRunId=<id> --skill=meticulous-zero-diff-task
meticulous agent submit-feedback --message="<一两句话>" --outcome=<helped|neutral|hindered> --testRunId=<id> --skill=meticulous-zero-diff-task

MCP

MCP

submit_feedback(message="<one or two sentences>", outcome="<helped|neutral|hindered>", testRunId="<id>", skill="meticulous-zero-diff-task")
undefined
submit_feedback(message="<一两句话>", outcome="<helped|neutral|hindered>", testRunId="<id>", skill="meticulous-zero-diff-task")
undefined