meticulous-zero-diff-task

差分なし（または差分の少ない）実装タスクを確実に進めるには、以下のワークフローに沿って、CLI または MCP コマンドを使用してください。

作業を開始する前に、meticulous-cli-update スキルを実行して、Meticulous CLI とスキルが最新であることを確認してください。ただし、この会話内ですでに実行済みの場合は、スキップしてください。

このスキルは、成功基準が視覚的な変化ではなく、視覚的な安定性であるタスクを対象としています。依存関係やバージョンのアップグレード、リファクタリング、移行（フレームワークやライブラリの入れ替え、ビルドツールの変更など）、および Meticulous の差分があれば機能として説明するのではなく、何かが壊れた兆候と見なされる同様の作業が該当します。また、差分の少ないタスク（大部分の出力は変更せず、想定内で十分に把握されている視覚的な変更が少数あるタスク）にも使えます。ワークフローは同じですが、修正ではなく最終的に説明が必要となる差分の数が少なくなります。

ステップ 1 -- タスクを実装する

タスクで説明されているコード変更（アップグレード、リファクタリング、移行）を行います。タスクが自然に複数の段階に分かれる場合は、適宜コミットしてください。これは Meticulous に特有のことではなく、通常の実装作業として行ってください。

ステップ 2 -- フロントエンドをビルドする

1. CI 設定の該当ステップを確認し、Meticulous が必要とするビルド成果物を調べます。
   • GitHub：uses: alwaysmeticulous/report-diffs-action/upload-assets@v1（ビルドアセット）または upload-container@v1（Docker イメージ）を含む .github/workflows/*.yml
   • GitLab：npx @alwaysmeticulous/cli ci upload-assets（ビルドアセット）または ci upload-container（Docker イメージ）を含む .gitlab-ci.yml（またはインクルードされている .gitlab/ci/*.yml）
   • Bitbucket：同じ npx @alwaysmeticulous/cli ci upload-assets または ci upload-container のステップを含む bitbucket-pipelines.yml
2. CI 設定で使用されている手順に従って、フロントエンドをビルドします。

ステップ 3 -- ビルドをアップロードしてテスト実行を開始する

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

# MCP (upload is not 1:1 — request an upload URL, upload the artifact yourself, then register it)
request_asset_upload(size=<zipByteSize>)      # or request_container_upload() — no required args
# ... upload the zip/image to the returned URL/registry yourself ...
register_asset_build(uploadId="<id>", commitSha="<sha>")      # or register_container_build(uploadId="<id>", commitSha="<sha>")
trigger_test_run(deploymentId="<deploymentId>", baseSha="<sha>")

MCP の trigger_test_run は baseSha／gitDiffOutput を自動推定しません（ベースはローカルで計算してください）。また、実行の完了を待たずに常にすぐ返します（デフォルトで処理をブロックする CLI とは異なります）。

リポジトリのディレクトリから trigger-test-run を実行すると、ベース（origin のデフォルトブランチとの merge-base）と git diff の両方が自動的に推定されます。オプションの全一覧については meticulous-cli のリファレンスを参照してください。特に、作業ツリーに未コミットの変更があっても構いません（エフェメラルコミットとして取得されるため、以下の各イテレーションの前にコミットする必要はありません）。

出力にある testRunId を控えておきます。

Step 4 -- 差分を確認し、なくなるまで繰り返します

meticulous-review スキルの手順（ステップ 1～4：agent test-run-diffs、スクリーンショット画像、DOM 差分、タイムライン）を使って差分を確認します。ただし、meticulous-review スキルで想定されている「期待どおりの変更か、リグレッションか」という判定方法の代わりに、次のルールを適用してください。

差分がないはずのタスクでは、返された差分はすべて、そうでないと証明されるまではバグとして扱います。 このスキルの前提は UI に変更がないことです。そのため、次のように判断します。

1. 差分がまったくない — このステップは完了です。ステップ 5 に進みます。
2. 差分が 1 つ以上ある — それぞれについて、スクリーンショット画像と DOM 差分（meticulous-review スキルのステップ 2～3 と同様）を確認し、何が、なぜ変わったのかを正確に把握します。DOM や画像だけでは原因が明らかでない場合は、タイムライン（同スキルのステップ 4）も使います。そのうえで、次のように分類します。
   • リグレッション（デフォルトの想定） — 変更によって実際に発生した副作用です。
   • 許容可能 — タスク自体の意図された、避けられない結果として積極的に説明できます（例：バージョンアップに伴うフッターのバージョン文字列の変更）。ここでは慎重に判断してください。差分が少ないタスクでは、このような差分が実際に少数あることもありますが、厳密に差分がないことを求めるタスクでは、通常はありません。まだ指摘を登録せず、ステップ 6 まで保留してください。暫定的なローカル反復ではなく、PR に対して CI が実行した実行結果に指摘を登録します。
   • 変更とは無関係 — meticulous-review スキルのステップ 5「無関係とみなされるもの」の定義に当てはまり、変更によって起きる可能性がない差分です。通常は、レンダリング時のノイズ、異なるフレームでのアニメーション、遅れて読み込まれるフォントや画像、サーバー生成タイムスタンプなどの環境ノイズが該当します。原因を説明できない差分にこのラベルを付けてはいけません。変更によって起きた可能性があるなら、ほかの分類のいずれかに該当します。
   • 修正できず、どちらとも確信をもって説明できない — その差分の対応を延々と繰り返さないでください。

リグレッションの場合は、すぐに却下してください。ここではあなたがレビュー担当者と実装担当者の両方ですが、後から追跡できる記録を残すためです。

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

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

次に、動作や出力が変更前のベースラインと一致するようコードを修正し、ステップ 3 に戻ってビルドと再実行を行います（新しいビルドで、ベースは同じものを使用）。後続の実行でその差分が再現されなくなったことを確認したら、コメントスレッドに「Fixed」と返信して対応を完了します。reject-diff が返した id を --commentId として渡してください。

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

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

修正できず、どちらとも確信をもって説明できない差分も、理由を添えて同様に却下します。スレッドに実情が反映されるようにしますが、未解決のままにしてください（「Fixed」とは返信しません）。人が判断できるよう、最終レポートと PR の説明（ステップ 5）で、その内容を明確かつ具体的に取り上げてください。

差分がなくなるか、残ったすべての差分が正当化されるか未解決として明示されるまで、ステップ 3～4 を繰り返します。

ステップ 5 -- PR を作成する

実行結果に問題がないこと（または、残っている差分すべてについて説明できること）を確認したら、未コミットの変更をコミットし、ブランチをプッシュして、PR を作成します。

作成者のクレジット： Meticulous は最終確認だけでなく、実装の反復作業を主導したため、コミットメッセージの末尾に Meticulous の共同作成者トレーラーを追加します。

<summary of the change>

Co-authored-by: Meticulous <87660985+alwaysmeticulous[bot]@users.noreply.github.com>

トレーラーは、空行の後、メッセージの最後の段落に1行ずつ記載します。Co-authored-by: Claude <[email protected]> のようなトレーラーがすでにある場合は、Meticulous が最初に記載される共同作成者となるよう、このトレーラーをその上に追加してください。GitHub では、上記のアドレスを使用してください。これは Meticulous の GitHub App に属するアドレスであるため、GitHub では Meticulous が共同作成者として表示されます。GitLab では、代わりに Co-authored-by: Meticulous <[email protected]> を使用してください。Bitbucket では共同作成者トレーラーがサポートされていないため、追加しないでください。git remote get-url origin を実行して、使用しているホストを確認します。

PR の説明には、タスクの概要と、Meticulous の結果を簡潔に記載します（失敗した非ビジュアルチェック、および Step 6 の Agent swarm の結果も含めます。これらは PR 自体の実行結果が報告された後に記載してください）。例：「Meticulous で検証済み：ゴールデンセットにビジュアル差分なし」。差分が残っている場合は、どのような差分か、また予想されるもの、あるいは避けられないものである理由を簡潔に列挙し、それぞれにリンクを付けてください：https://app.meticulous.ai/test-runs/<testRunId>/replay-diff/<replayDiffId>?screenshot=<screenshotName>。

Step 6 -- PR 自身のテスト実行結果が一致することを確認する

CI がプッシュしたコミットに対して独自の Meticulous テスト実行を開始したら、ローカルで検証済みの結果と同じ結果が表示されていることを確認します。これにより、ローカルのビルドと CI のビルドのずれ（依存関係のロックファイルの不一致や、CI でのみ設定されている環境変数など）を検出できます。

# CLI (resolves from local git HEAD — already the pushed commit)
meticulous agent test-run-diffs

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

HEAD から解決する代わりに、--testRunId <id>、--commitSha <sha>、または --prNumber <n> を指定して実行を特定することもできます（MCP では、get_test_run_diffs(prNumber=<n>) を直接指定します）。

CI がまだ実行を開始していない場合は、自分で再実行を開始するのではなく、待ってから再試行してください。PR の実行は、人間のレビュアーが確認するものと同じ CI パイプラインから行われる必要があります。PR の実行でローカルの反復時とは異なる差分が表示された場合は、新たな兆候として扱い、PR の testRunId を使って Step 4 に戻ります。

ここにまだ残っていて、修正せずに妥当と判断した差分（Step 4 の許容可能の分類）については、それぞれの理由を通常のレビューコメントとして記録してください。これは CI と人間のレビュアーが実際に確認する実行結果です。

# CLI
meticulous agent create-diff-comment --replayDiffId=<id> --screenshotName=<name> --text="<why it's justified>" --x=<0..1> --y=<0..1>

# MCP
create_diff_comment(replayDiffId="<id>", screenshotName="<name>", text="<why it's justified>", x=<0..1>, y=<0..1>)

ignore-diff は、Step 4 で無関係と判断した差分、つまり変更とまったく関係のない差分にのみ使用してください。

# CLI
meticulous agent ignore-diff --replayDiffId=<id> --screenshotName=<name> --reason="<why it's unrelated>" --x=<0..1> --y=<0..1> [--reportFlake]

# MCP
ignore_diff(replayDiffId="<id>", screenshotName="<name>", reason="<why it's unrelated>", x=<0..1>, y=<0..1>, reportFlake=<true|false>)

リプレイ自体が非決定的で、Meticulous が決定的にすべきだった場合は、--reportFlake を追加します（meticulous-review スキルの Step 5「Report likely engine bugs」を参照）。これにより、Meticulous はリプレイエンジンのバグの可能性が高い問題として調査します。フレークの報告は、1 回の実行につき 1 回だけ行ってください。同じフレークが複数の差分に現れる場合は、そのうち 1 つにのみ追加します。

コメントによって判定が決まることはありません。差分は unreviewed のままで、チェックも保留状態のままですが、人間の PR レビュアー向けに理由を記録できます。

非視覚的チェック（PR の実行に含まれる場合のみ）。 meticulous agent test-run-check --availableIds で確認します。プロジェクトがチェック用に設定されていないために拒否される場合、または何も表示されない場合は、スキップしてください。それ以外の場合は、meticulous-review スキルの Step 8 と同様に各失敗チェックを処理します。ただし、Step 4 のルールに従って分類します。差分がないタスクの場合、失敗チェックは反証されるまでリグレッションとして扱います。

• リグレッション：修正して Step 3 に戻ります。修正できない場合は、理由を添えて reject-check します。
• 変更と無関係：理由を添えて ignore-check します。
• 許容可能：理由を添えて approve-check します。

approve-check と ignore-check を使用するには、プロジェクトの Enable approve/ignore check actions 設定が必要です。使用を拒否された場合は、チェックを未決定のままにします。チェックの理由は保存されますが、Meticulous アプリ上でユーザーに表示されることはありません。そのため、失敗したチェックをすべて、判定と理由とともに PR の説明に記載してください。

Agent swarm（PR のコミットに実行結果がある場合のみ）。 一部のプロジェクトでは、ブラウザーでプルリクエストのビルドをテストし、いくつかのテストケースを報告する Meticulous のホスト型エージェント、Agent swarm も実行します。meticulous-review スキルの Step 9 に従って実行結果を確認します。結果は参考情報ですが、修正プロンプト付きの fail ケースは例外です。差分がないタスクでは、そのようなケースはリグレッションとして扱います。まずプロンプトで指摘されたコードがブランチ上にあることを確認し、meticulous-fix スキルの Step 4 に従って修正して Step 3 に戻ります。ただし、チェックで失敗が変更と無関係だと判明した場合（check.linkedToChange が "no" の場合）は除きます。実行結果の概要（例：「4 ケース：3 件成功、1 件ブロック」）と、対応しなかった修正プロンプト、その理由を PR の説明に追記してください。

Step 7 -- Meticulous にフィードバックを報告する

最後の手順として、Meticulous チームに短いフィードバックを 1 件送信します。この種類のタスクで反復して問題を解消する流れがうまく機能したか、分かりにくい点はあったか、何があればもっと簡単だったかを伝えてください。

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

# MCP
submit_feedback(message="<one or two sentences>", outcome="<helped|neutral|hindered>", testRunId="<id>", skill="meticulous-zero-diff-task")