meticulous-review

Meticulous のテスト実行を確認するには、以下のワークフローに従い、説明にある CLI または MCP コマンドを使って手順を進めてください。実行結果にまだレビューが必要か、すでに誰かがレビューしたかを事前に把握しておく必要はありません。ステップ 1 でレビュー状態を読み取り、その結果に応じて後続の手順が決まります。

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

レビュー中は、たとえこの会話の前のほうで自分が変更を実装した場合でも、実装者ではなくレビュー担当者として振る舞ってください。各差分は、その内容に基づいて分類してください。修正はその後の別の工程（ステップ 12）で行うものであり、レビューと並行して行うものではありません。実装中に Meticulous を繰り返し実行して期待どおりになるまで確認したい場合は、意図した視覚的変更を伴う機能開発には meticulous-iterative-dev スキルを、UI を変更してはならない場合には meticulous-zero-diff-task スキルを参照してください。

Step 0 -- 期待される変更を把握する

差分を確認する前に、この PR が本来どのような視覚的変更をもたらすものか把握してください。

• 変更の全容をすでに把握している場合（同じ会話内で変更を実装した場合、またはユーザーがタスクを説明したばかりの場合）は、その情報を使ってください。
• それ以外の場合 — PR の説明を取得し（GitHub の場合は gh pr view <number> --json title,body、GitLab の場合は glab mr view <id> --output json --jq '{title,description}'、Bitbucket の場合は Teamwork Graph CLI が利用可能なら twg bitbucket pull-requests get <id> を実行してください。インストール済みであれば twg-engineering-work スキルに従い、Bitbucket トークンを求められた場合は twg setup bitbucket を一度実行してください。これらが使えない場合は GET /2.0/repositories/{workspace}/{repo_slug}/pullrequests/{id}?fields=title,description を使用してください）、想定される視覚的変更として明記されている内容を簡潔な箇条書きにまとめてください。
• 変更について何も触れられていない場合は、そのことを明記してください。その場合、既知で受け入れ済みの影響として記録されているものがないため、以下の各差分をより慎重に確認する必要があります。

Step 1 -- レビュー状態とともにリプレイ差分の概要を取得する

ローカルのチェックアウトからコマンドを実行し、現在のコミットの git HEAD に対応するテスト実行を特定してください。まず HEAD が CI の実行対象となったリモートの HEAD と一致していることを確認してください（一例として git pull を実行します）。一致していないと、古い実行結果や存在しない実行結果をレビューするおそれがあります。

# CLI (infers the run from local git HEAD)
meticulous agent test-run-diffs --includeReviews

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

replayDiffId／screenshotName の行からなる TSV が返されます。これは代表的な実際の視覚的差分を優先度順に並べたサブセットです。上から順に確認してください。--includeReviews を指定すると、各行に decision と openComments が追加されます。HEAD からの特定ではなく実行を明示的に指定するには、--testRunId <id>、--commitSha <sha>、または --prNumber <n> を渡してください（MCP では get_test_run_diffs(prNumber=<n>) を使うと、get_test_run_for_commit の手順を省略できます）。CLI は既定で実行が完了するまで待機します（進行中の実行を報告してすぐ終了するには、代わりに --dontWaitForTestRunToComplete を渡してください）。MCP は待機しないため、status が complete または failed になるまでポーリングを続けてください。

レビュー状態によって、各行で必要な対応が決まります。

• unreviewed、未解決のコメントなし — レビューしてください。ステップ 2～6 を実施します。
• rejected、または未解決のコメントあり — すでに誰かが確認しているため、再レビューしないでください。ステップ 7 で取り上げます。
• accepted または ignored、未解決のコメントなし — すでに判断済みのため、対応は不要です。

レビューが必要な行がない場合は、ステップ 7 に進んでください。それ以外の場合、未レビューの各行について、ステップ 0 の内容と照合するか、フラグを付けてください（「判定ガイド」を参照）。PR に問題がないと結論づける前に、すべての行を確認する必要があります。

Step 2 -- スクリーンショット画像を取得する

代表的なスクリーンショットごとに、次の操作を行ってください。

# CLI (downloads images to ~/.meticulous/agent-images/ and prints local paths)
meticulous agent image-files --replayDiffId <replayDiffId> --screenshotName <screenshotName>

# MCP (no download-to-disk tool — returns signed URLs instead; fetch them to view the images)
get_image_urls(replayDiffId="<replayDiffId>", screenshotName="<screenshotName>")

before、after、diffImage を開く（または取得する）ことで変更を確認してください。diffImage は通常、どのピクセルが変化したかを正確に強調表示するため、最も参考になります。DOM の差分が明確に見える場合でも、必ず画像を確認してください。

ステップ 3 -- DOM の差分を調べる（構造の詳細）

# CLI
meticulous agent dom-diff --replayDiffId <replayDiffId> --screenshotName <screenshotName>

# MCP
get_dom_diff(replayDiffId="<replayDiffId>", screenshotName="<screenshotName>")

任意：--context <N|full>（CLI）で、各ハンクの前後に表示するコンテキスト行数を指定します（デフォルトは 3）。

出力は統一形式の差分（+/-、インデントは削除）で、独立した変更ごとに [diff N] 見出し付きのブロックが 1 つ出力されます。たとえば、以下のようになります（説明用の例であり、実際の出力ではありません）。

[diff 0]
 <div class="item">
-  <span class="label">old label</span>
+  <span class="label" data-flag="true">new label</span>
 </div>
[diff 1]
 <ul class="list">
+  <li>new item</li>
 </ul>

ステップ 4 -- リプレイのタイムラインを取得する（任意。予期しない差分の診断用）

差分が予期しないもので、画像や DOM から理由が明らかでない場合：

# CLI
meticulous agent timeline-diff --replayDiffId <replayDiffId>

# MCP
get_timeline_diff(replayDiffId="<replayDiffId>")

TSV の列：diff（ は同一、- は削除、+ は追加、! は変更）、timeMs、event（user/screenshot/network/console/など）、description。視覚的な変化の原因となりそうな、ネットワークリクエストの失敗、予期しないリダイレクト、タイミングの異常を探してください。

ステップ 5 -- 判断ガイド

代表的なスクリーンショットごとに、差分画像と DOM の差分をステップ 0 の想定と比較します。

• 想定どおり — ステップ 0 で想定された変更のいずれかと一致する（または、実装全体のコンテキストを踏まえると、明らかに望ましい結果である）ものです。差分が実際にその変更だけを示しており、それ以外の変更が含まれていないことを確認してください。変更の種類は想定どおりでも、同じスクリーンショットに無関係な回帰が紛れ込んでいることがあります。指摘事項はありません。approve-diff が利用できる場合は、承認してください（ステップ 6）。
• 意図しない変更 — ステップ 0 で想定されていない変更です。タイムラインを使って、リクエストの失敗、リダイレクト、その他の異常がないかを確認してから、指摘してください。
  • 回帰の可能性あり（実際の副作用、または明らかに誤った結果）→ 却下。
  • レビュー対象の変更とは無関係（下記参照）→ 無視。

どちらの場合も、その差分は指摘済みとして扱われ、黙って除外されることはありません。人による確認が必要です。

無関係とみなされるもの。 変更によって引き起こされる可能性がない差分のみを無視してください。

• 描画ノイズ：通常、DOM の変更を伴わないサブピクセルやアンチエイリアスの違い。
• 異なるフレームでキャプチャされたアニメーション、スピナー、カルーセル、動画。
• フォントや画像の読み込みの遅延、またはネットワーク応答の到着順の違い。
• 環境ノイズ：サーバー側で描画されたタイムスタンプやデータ、ビルドバージョンや SHA、サードパーティのコンテンツ。

無視する前に、変更が影響箇所に到達し得ないこと（PR の差分に、その画面やコンポーネントへつながるものがないこと）と、タイムラインに説明可能な差異がないことを確認してください。リプレイの経路が異なっていた場合（クリック先が別の場所になった、片方だけでメニューが開いたなど）、その違いが変更によって引き起こされ得ない場合に限り、無関係と判断できます。エンジン独自のフレークラベルだけでは判断できません。次のものは決して無視しないでください。

• 説明できない差分。
• 変更によって引き起こされた可能性がある差分。たとえ無害でも、意図したものなら承認し、そうでなければコメントを付けて未判断のままにします。
• 新しいコードでは対応できなくなった、記録済みのネットワーク応答（例：「Missing field」エラー）。これは変更が原因です。
• それ自体は無関係でも、スクリーンショットに紛れ込んでいる回帰。これは却下してください。

判断に迷う場合は、差分を未判断のままにし、create-diff-comment で説明してください。

エンジンのバグと思われるものを報告する。 リプレイが非決定的だった差分を無視する場合は、--reportFlake を追加してください。Meticulous は描画、アニメーション、タイマー、日付、乱数、ネットワークの順序、または経路が異なるリプレイを決定的にできるはずなのに、そうならなかったケースが対象です。Meticulous は、これをリプレイエンジンのバグの可能性として調査します。フレークが表示された差分すべてではなく、実行ごとに 1 回だけ報告してください。1 つの原因によって、多数の差分で同じフレークが発生する場合（例：画面ごとに異なる時刻やアニメーション）、それらの差分はそれぞれ無視しますが、--reportFlake を追加するのはそのうち 1 つだけです。アプリが実際に返した内容の違い（サーバー側で描画されたタイムスタンプ、ビルドバージョン、サードパーティのコンテンツなど）には追加しないでください。これらはアプリの所有者が修正します。たとえば、meticulous-ignore クラスを使って要素を非表示にします。

まずレビューし、その後に修正する。 レビュー中にコードを変更しないでください。すべての差分の分類と指摘を終えてから、ステップ 12 で修正が必要なものに対処します。

ステップ 6 -- 差分を却下または承認する

# CLI
meticulous agent reject-diff --replayDiffId=<id> --screenshotName=<name> --reason="<why>" --x=<0..1> --y=<0..1>
meticulous agent approve-diff --replayDiffId=<id> --screenshotName=<name>
meticulous agent ignore-diff --replayDiffId=<id> --screenshotName=<name> --reason="<why>" --x=<0..1> --y=<0..1> [--reportFlake]
meticulous agent create-diff-comment --replayDiffId=<id> --screenshotName=<name> --text="<note>" --x=<0..1> --y=<0..1>

# MCP
reject_diff(replayDiffId="<id>", screenshotName="<name>", reason="<why>", x=<0..1>, y=<0..1>)
approve_diff(replayDiffId="<id>", screenshotName="<name>")
ignore_diff(replayDiffId="<id>", screenshotName="<name>", reason="<why>", x=<0..1>, y=<0..1>, reportFlake=<true|false>)
create_diff_comment(replayDiffId="<id>", screenshotName="<name>", text="<note>", x=<0..1>, y=<0..1>)

意図しないと分類した差分はすべて、最終レポートに含めるだけでなく、reject-diff または ignore-diff を呼び出してください。--reason には上記の分類で使った簡潔な説明を指定し、--x／--y には差分画像から推定した、変更領域のおおよその正規化座標を指定します。記録に残したい内容について、判定を伴わない中立的な方法として create-diff-comment を使えます。

approve-diff は利用できますか？ Enable approve/ignore diff actions 設定が有効なプロジェクトでのみ利用できます。MCP 経由では、この設定が有効な場合に限り approve_diff が提示されます。CLI では事前に確認できないため、最初に想定どおりと判断した差分に対して呼び出してください。403 エラーが「Agents may not approve diffs on project …」で始まる場合は無効なので、以降は承認に関するすべての操作を省略してください。

想定どおりと分類した差分はすべて approve-diff を呼び出してください。却下や無視とは異なり、理由は不要です。

対称ではありません： reject-diff は、人間による却下と同様に、実際にブロックする判定を書き込みます。approve-diff が利用できる場合、approve-diff と ignore-diff も、差分を解決する実際の判定を書き込みます。一方、それ以外の場合、ignore-diff は判定を行わず、コメントを残すだけです。そのため差分は unreviewed のままとなり、チェックも保留状態のままです。したがって、最終レポートで解決済みであるかのように誇張して報告しないでください。

ステップ 7 -- 実行の残りを確認する

ステップ 1～6 で確認したのは、代表的なサブセットのみです。ステップ 1 で確認対象が見つからなかった場合も、このステップを実行してください。

修正対象を集めます。 実行内で却下されている、または未解決のコメントがある差分をすべて一覧表示します。

# CLI
meticulous agent test-run-diffs --onlyRejected --onlyWithComments --includeReviews

# MCP
get_test_run_diffs(testRunId="<id>", onlyRejected=true, onlyWithComments=true, includeReviews=true)

--only* フラグは追加条件として適用され（却下されている差分、未解決のコメントがある差分、またはその両方）、代表的なサブセットに限定されることはありません。却下、または変更を求めるコメント（diff-comments／get_diff_comments でスレッドを確認できます）がある差分は、自分で却下した差分も含め、ステップ 12 の修正対象となります。無視や承認の理由だけを説明するコメント（このスキル自身が残す ignore-diff と approve-diff のコメントなど。エージェントによる無視が許可されていないプロジェクトでは、無視した差分は unreviewed のままです）や、判断に迷った差分に残したメモは、修正対象ではありません。

残りの差分を判定します（approve-diff が利用できる場合のみ）。 すべての差分に判定が付くまで、チェックは合格になりません。ステップ 6 で approve-diff が利用できないとわかった場合は、この部分を省略してください。利用できない場合、ここでチェックを解決する方法はありません。それ以外の場合、まだ判定されていない差分を一覧表示します。

# CLI
meticulous agent test-run-diffs --includeAllDiffs --onlyUnreviewed --includeReviews

# MCP
get_test_run_diffs(testRunId="<id>", includeAllDiffs=true, onlyUnreviewed=true, includeReviews=true)

未解決のコメントがない各行について、最初の差分と同様にステップ 2～6 を実施します。未解決のコメントがある行は上記で扱います。まだ approve-diff を呼び出していない場合は、ステップ 6 と同じように、想定どおりと分類した最初の行で利用可能かどうかがわかります。利用できない場合は、そこで中止してください。--includeAllDiffs は常に指定してください。指定しないと、代表的なサブセット内に未判定の差分がある限り、--onlyUnreviewed の対象はそのサブセットに限定されたままになります。

ステップ 8 -- ビジュアル以外のチェックを確認する（実行にチェックがある場合のみ）

スクリーンショットの差分に加えて、実行にはビジュアル以外のチェックが含まれる場合があります。accessibility、network-requests、react-component-renders などの組み込みチェックや、プロジェクト独自の CI が報告するカスタムチェックです。ほとんどのプロジェクトにはチェックがないため、まずこの実行にチェックがあるかどうかを確認します。

# CLI (same run selector as Step 1)
meticulous agent test-run-check --availableIds

# MCP
get_test_run_check_available_ids(testRunId="<id>")

プロジェクトがチェックに対応するよう設定されていないためにこの操作が拒否された場合、確認すべきチェックはありません。ステップ 9 に進んでください。リストが空の場合、まだ結果が報告されていない可能性もあるため、チェックがないと判断する前に、コマンドの通知に従って再試行してください。

一覧にあるチェックごとに、レポートを取得します。

# CLI
meticulous agent test-run-check --checkId=<checkId> [--checkType=custom]

# MCP
get_test_run_check(testRunId="<id>", checkId="<checkId>", checkType="builtin|custom")

判断が必要なのは失敗したチェックだけです。つまり、検出事項への対応が必要なチェックです。成功したチェックや、警告のみのチェックには対応不要です。レポートには検出事項の説明が記載されています。組み込みチェックの場合、meticulous agent test-runs --prNumber=<n> --includeCheckIssueCounts を使うと、実行ごとの失敗数（checkFailureCount）も確認できます。以下の確認コマンドは、対応が必要でないチェックを拒否するため、拒否された場合も対応不要と判断できます。

ステップ 5 の差分の分類方法に従い、ステップ 0 の想定と照らして、失敗したチェックを分類し、対応してください。

• 想定どおり：PR で意図的に追加されたリクエストなど、変更によって意図された結果です。承認してください。
• 潜在的なリグレッション → 却下してください。
• レビュー対象の変更とは無関係 → 差分と同じルールに従って無視してください。たとえば、PR が変更していないコードやページに関するもので、変更が原因となる妥当な可能性がない検出事項に限ります。説明できない検出事項を無視してはいけません。

# CLI (--prNumber=<n> can stand in for --testRunId)
meticulous agent reject-check --testRunId=<id> --checkId=<checkId> [--checkType=custom] --reason="<why>"
meticulous agent approve-check --testRunId=<id> --checkId=<checkId> [--checkType=custom] --reason="<why>"
meticulous agent ignore-check --testRunId=<id> --checkId=<checkId> [--checkType=custom] --reason="<why>"

# MCP
reject_check(testRunId="<id>", checkId="<checkId>", checkType="builtin|custom", reason="<why>")
approve_check(testRunId="<id>", checkId="<checkId>", checkType="builtin|custom", reason="<why>")
ignore_check(testRunId="<id>", checkId="<checkId>", checkType="builtin|custom", reason="<why>")

これはステップ 6 と同様ですが、次の違いがあります。

• 理由はユーザーには表示されません。 理由は判断の根拠として保存され、エージェントは check-comments で読み返せますが、Meticulous アプリには表示されません。それでも、理由が任意の approve-check の場合も必ず記入し、最終報告にも繰り返し記載してください。ユーザーが確認できるのは最終報告です。
• **approve-check と ignore-check には「Enable approve/ignore check actions」**が必要です。これは差分に対する設定とは別のプロジェクト設定です。この設定が無効だと、どちらも拒否されます。ignore-diff とは異なり、コメントのみを残す代替手段はありません。MCP 経由では、この設定が有効な場合にのみ提示されます。拒否された場合はチェックを未判断のままにし、最終報告で人間の判断が必要なものとして明記してください。reject-check は常に実行できます。
• チェックに対する中立的なコメントはありません。判断に迷う場合は未判断のままにし、最終報告でその理由を説明してください。

ステップ 9 -- Agent swarm の結果をまとめる（コミットに結果がある場合のみ）

一部のプロジェクトでは Agent swarm も実行されます。これは Meticulous がホストするエージェントで、プルリクエストのビルドをブラウザーでテストし、テストケースをいくつか報告します。各ケースのステータスは pass、fail、blocked、skipped のいずれかです。承認、却下、無視の対象ではありません。修正プロンプトのあるケースを除き、結果は参考情報です。同じコミットの実行を探してください。

# CLI (same run selector as Step 1; waits up to 10 minutes for a run still in progress)
meticulous agent agent-swarm-run

# MCP (a run still in progress returns { status: 'processing' }: poll every 10s, for at most 10 minutes)
get_agent_swarm_run(commitSha="<sha>")

そのコミットに対する Agent swarm の実行がない、または計画のみの実行しか報告されない場合は、ステップ 10 に進んでください。実行が 10 分経過しても進行中の場合、完了しなかった場合（理由は errorMessage に記載されています）、またはテスト不可と判定された場合（notTestable）は、その旨を最終報告に記載してください。

それ以外の場合は、すべてのケース（title、status、outcomeSummary）を確認し、何がテストされ、何がテストされなかったかを把握してください。重要なのは修正プロンプトのあるケースです。これは、独立したチェッカーによって確認された失敗で、すぐに使える修正用プロンプトが用意されています。該当するのは fail のケースだけなので、それぞれを取得し、出力に fixPrompt があるか確認してください。

# CLI
meticulous agent agent-swarm-run-case --swarmRunId=<id> --caseIndex=<n> --json

# MCP
get_agent_swarm_run_case(swarmRunId="<id>", caseIndex=<n>)

ケースに修正プロンプトがあるかどうかは、その内容より重要です。必ず報告してください。ステップ 12 での修正対象になります。

Step 10 -- 最終レポート

重要なビジュアル変更をすべて取り上げ、Step 8 で失敗したチェックと Step 9 の Agent swarm の概要も含めます。

1. 想定された変更 — それぞれ簡潔に、何が変わったか、Step 0 のどの想定に合致するか、承認したかどうかを1～2行で記載します。
2. フラグを付けた差分（ある場合） — レビューの中心となる項目なので、最も詳しく記載します。replayDiffId/screenshotName（リンク先：https://app.meticulous.ai/test-runs/<testRunId>/replay-diff/<replayDiffId>?screenshot=<screenshotName>）、却下または無視したかどうか、フラグを付けた理由（Step 6）、変更の見た目、原因についての最善の推測を記載します。
3. 失敗したチェック（ある場合） — それぞれのチェック ID とタイプ、検出された内容、承認・却下・無視のいずれか、または未判断のままにしたかどうか、そしてアプリには表示されないため、その理由をすべて記載します。
4. Agent swarm（コミットに実行結果がある場合） — https://app.meticulous.ai/test-runs/<testRunId>?tab=agent-swarm へのリンクとともに、結果（例：「4 ケース：3 件合格、1 件ブロック」）と、おおよそどのような内容を検証したか、または実行が完了しなかった理由やテストできなかった理由を1～2行で記載します。失敗した各ケースの名前と outcomeSummary を記載し、修正プロンプトがあるケースを示します。これらは meticulous-fix スキルで対応できます。
5. レビュー済みの項目（Step 7 で見つかったものがある場合） — 他の人が却下した差分やコメントを付けた差分について、それぞれのコメントで求められていることと、次の対応（Step 12）で修正するか、PR の作成者に任せるかを記載します。

すべての差分と失敗したチェックが、それぞれ対応済みかフラグ付きになって初めて PR は問題ない状態です。フラグを付けたものがある場合は、その旨もフラグとあわせてユーザーにはっきり伝えてください。approve-diff が利用できる場合、未判断のままにした差分も必ず示してください。未判断の差分があると、チェックは保留状態のままになります。未判断のままにした失敗チェックについても同様に記載してください。

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

レビューを完了するために必ず実施してください。レビューそのものの一部であり、ユーザーから依頼されるのを待つ必要はありません。 簡潔なメモを1つ送信します。Meticulous が実際の問題を検出したか、分かりにくい点はあったか、レビューをより簡単にするには何があればよかったかを伝えます。良かった点のフィードバックも歓迎されます。使いにくさの報告だけが目的ではありません。

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

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

Step 12 -- 修正が必要な項目を引き継ぐ

修正対象をまとめます。Step 7 の差分（却下したものも含む）、却下したチェック（Step 8）、修正プロンプトがある Agent swarm のケース（Step 9）です。該当するものがなければ、これで完了です。

• この PR のコードを担当している場合 — 変更を実装した場合、またはユーザーから PR を通る状態にするよう依頼された場合は、ここで meticulous-fix スキルに従って対応します。このスキルはコメントを読み、コードを修正し、各スレッドに返信して、プッシュし、次回の実行で確認します。
• 他の人の PR をレビューしているだけの場合 — コードは変更しません。最終レポート（Step 10）ですでに PR の作成者向けの修正対象を示しているので、これで完了です。
• プッシュ済みのコミットではなくローカルビルドの実行の場合（meticulous-test スキルからここに案内された場合など）— 最終レポートを作成したら終了します。meticulous-fix はコミット、プッシュ、CI の完了待ちを行いますが、このループの進め方とは異なります。