meticulous-fix

すでにレビューされ、却下された差分を修正するには、以下のワークフローに沿って、CLI または MCP コマンドを使用してください。

開始する前に、meticulous-cli-update スキルを実行して、Meticulous CLI とスキルを最新の状態にしてください。ただし、この会話ですでに実行されている場合はスキップしてください。

このスキルでは、すでにレビューが行われていることを前提とします。ユーザー（または meticulous-review スキル）が実行結果を確認し、実際に問題のある差分を却下しています。何が問題なのか、または何をすべきかを説明するコメントが残されている場合もありますが、コメントがあるとは限りません。ここでの作業は、完全なレビューよりも範囲が狭いものです。却下されていない差分を再検討したり、却下そのものを疑ったりせず、何を変更すべきかを判断して実行してください。

Step 1 -- 却下された差分と、コメントが付いた差分を取得する

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

# MCP (git context is never inferred — pass a commit or test run explicitly)
get_test_run_diffs(testRunId="<id>", onlyRejected=true, onlyWithComments=true, includeReviews=true)

引数を指定しない場合、CLI はローカルの git HEAD から実行を特定します。明示的に指定するには、--testRunId <id>、--commitSha <sha>、または --prNumber <n> を渡してください（MCP では testRunId の代わりに prNumber も指定できます）。

重要 — --only* フラグは加算的（OR 条件）です。 --onlyRejected と --onlyWithComments の両方を渡すと、却下された差分、未解決のコメントがある差分、またはその両方に該当するすべての差分が返されます。両方に該当する差分だけではありません。正式には却下されていない差分へのコメントにも、対応すべき指示が含まれている可能性があるためです。--includeAllDiffs は暗黙的に指定され、選択したサブセットだけでなく、実行全体が対象になります。--includeReviews を指定すると decision／openComments 列が追加され、各行がどのケースに該当するかを確認できます。

コメントがある行が、すべて修正対象とは限りません。 meticulous-review スキルの ignore-diff は、その差分が変更と無関係であることを示す注記を投稿し、approve-diff は承認理由を説明する注記を投稿する場合があります。どちらも修正指示ではありません。Step 1 の行を確認する際、未解決のコメントがこれらだけの差分はスキップし、そのスレッドには手を加えないでください。

却下されたチェック（実行に存在する場合のみ）。 実行には、accessibility や network-requests など、視覚以外のチェックが含まれる場合もあります。meticulous agent test-run-check --availableIds（MCP：get_test_run_check_available_ids）で一覧を取得してください。プロジェクトがチェック用に設定されていないために拒否された場合、または何も表示されない場合、チェックはありません。この段落の残りはスキップしてください。該当する場合は、各チェックに記録された理由を確認してください。

# CLI (--prNumber=<n> can stand in for --testRunId)
meticulous agent check-comments --testRunId=<id> --checkId=<checkId> [--checkType=custom]

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

未解決のコメントが Verdict: reject で始まるチェックは、エージェントによって却下されており、コメントの残りに理由が記載されています。このチェックは修正対象であり、その理由が指示になります。Verdict: approve または Verdict: ignore で始まるコメントは対象外です。人による却下では、ここに理由は記録されません。ユーザーからチェックが却下されたと伝えられた場合も、修正対象として扱い、レポートを基に作業してください。修正対象のチェックごとに、meticulous agent test-run-check --checkId=<checkId> [--checkType=custom]（MCP：get_test_run_check）でレポートを取得し、指摘事項そのものを確認してください。

Agent swarm の修正プロンプト（コミットに実行結果がある場合のみ）。 プロジェクトによっては、Meticulous がホストするエージェントである Agent swarm も実行されます。このエージェントは、ブラウザー上でプルリクエストのビルドをテストし、いくつかのテストケースを報告します。その結果は参考情報ですが、fail ケースに修正プロンプトがある場合は例外です。これはチェッカーが失敗と判定したケースで、修正用のプロンプトがあらかじめ用意されています。これらのケースも修正対象として検討してください。コミットの実行を確認し、失敗したケースを一覧表示してください。

# CLI (same run selector as above; waits up to 10 minutes for a run still in progress)
meticulous agent agent-swarm-run --status=fail

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

コミットに対する Agent swarm の実行がない場合、プランのみの実行しかない場合、または失敗したケースがない場合は、この段落の残りをスキップしてください。実行が10分経っても完了しない場合は、最終報告でその旨を伝えてください。それ以外の場合は、上に表示された swarmRunId で実行を指定して、失敗した各ケースの詳細を取得し、fixPrompt があるケースを残してください。

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

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

ケースの check.linkedToChange が "no" の場合、チェッカーはこの PR が失敗の原因ではないと判定しています。たとえば、以前から存在するバグなどです。ユーザーから修正を依頼されない限り、修正せずに報告してください。

ステップ 2 -- コメントがある差分のレビューコメントを読む

openComments > 0 の差分ごとに、次の操作を行います。

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

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

これが主な指示元です。通常、コメントには何が問題なのか、そして多くの場合、どう対処すべきかが書かれています。その差分に取りかかる前に、すべてのコメントと返信（古い順にネスト）を読んでください。返信によって、以前のコメントの要望が絞り込まれたり、変更されたりすることがあります。

コメントのない却下済み差分については、ここで読むものはありません。次に確認する視覚的・構造的なコンテキストを頼りにしてください。

ステップ 3 -- 視覚的・構造的なコンテキストを確認する

各差分について、meticulous-review スキルの調査手順を再利用します。

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

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

出力形式については meticulous-review スキルのステップ 2～3 を参照してください。原因がまだはっきりしない場合は、任意で agent timeline-diff も使用できます。

コメントのない却下済み差分の代替手順： この場合、コンテキストは単なる補足情報ではなく、主な指示元になります。meticulous-review スキルの判断ガイドと同様に扱い、却下が示している回帰を自分で判断してください。

ステップ 4 -- 根本原因となっているコードを修正する

修正対象（却下済み差分、またはコメントで具体的な修正を求められている却下されていない差分）ごとに、コメントの指示（コメントがない場合は、特定した回帰）を解決するコード変更を行います。ステップ 1 の無視のみのスレッドはスキップしてください。コードを変更せず、返信もしないでください。1 つのコード変更で複数の修正対象差分を同時に解決できる場合があります（たとえば、1 つのコンポーネントの不具合が複数のスクリーンショット差分を引き起こしている場合など）。同じ根本原因を繰り返し修正しないでください。

修正対象の差分すべてについて、修正できたかどうかにかかわらず、コメントスレッドに返信して（スレッドがない場合は作成して）対応を完了します。

# CLI
meticulous agent reply-to-diff-comment --commentId=<id> --text="<message>"
meticulous agent create-diff-comment --replayDiffId=<id> --screenshotName=<name> --text="<message>" --x=<0..1> --y=<0..1>

# MCP
reply_to_diff_comment(commentId="<id>", text="<message>")
create_diff_comment(replayDiffId="<id>", screenshotName="<name>", text="<message>", x=<0..1>, y=<0..1>)

差分にすでにコメントスレッドがある場合は reply-to-diff-comment を使用してください。ステップ 2 で確認したスレッドの root id（replyToCommentId が空欄の行）を渡し、返信の id は渡さないでください。create-diff-comment は、却下された差分に既存のコメントがない場合（コメントなしの代替手順の場合）にのみ使用してください。返信するスレッドがないためです。

• 修正済み — 「Fixed.」と返信またはコメントします。
• 修正不可（コメントで、実際には不可能なことを求めている場合。別の要件と矛盾している、存在しない動作について述べている、見つからないものを参照しているなど） — 推測で対応せず、レビュー担当者が再度尋ねなくても済むよう、理由を説明します。

いずれの場合も、次の修正対象差分に進み、最後に報告します（下記の最終報告を参照）。

ステップ 1 の修正対象チェックも同様に、却下理由とレポートの指摘事項をもとに修正します。チェックには返信するコメントスレッドがありません。チェックの却下理由は Meticulous アプリ上で確認できないためです。各チェックについて、修正したかどうかと、その理由を最終報告および PR コメント（ステップ 6）に記録してください。

修正プロンプトがある Agent swarm のケースでは、まず fixPrompt（ケースの出力フィールド。CLI の agent-swarm-run-case --fixPrompt ではこれだけが出力されます）を確認します。これは出発点であり、検証済みのパッチではありません。チェッカーは実行時にテストしたコミットを確認しているため、記載されているすべてのファイルと行を、まず現在のブランチと照合してください。エージェントが遭遇した症状ではなく、根本原因を修正します。チェックと同様、ケースにもコメントスレッドはありません。各ケースで行った対応を、最終報告と PR コメントに記録してください。

ステップ 5 -- コミットしてプッシュし、CI の確認を待つ

1. 修正をコミットします。後で git log を見るだけで内容が分かるよう、コミットメッセージに Meticulous のレビュー指摘に対応したことを具体的に記載します。

   Fix layout shift in checkout header
   
   Addresses Meticulous review feedback on test run <testRunId>:
   - <replayDiffId>/<screenshotName>: <brief on what was wrong and the fix>
   - Agent swarm case "<title>": <brief on what was wrong and the fix>
   
   Co-authored-by: Meticulous <87660985+alwaysmeticulous[bot]@users.noreply.github.com>
   

   作者クレジット： メッセージの末尾に、上記の Co-authored-by: Meticulous トレーラーを付けます。この修正は Meticulous のレビュー指摘を受けたものだからです。トレーラーはメッセージの最後の段落に、空行を挟んで、1 行に 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 で使用しているホストを確認してください。

2. ブランチをプッシュします（git push origin <branch> — git のプッシュルールを参照してください）。

3. プッシュしたコミットに対して、CI が新しい Meticulous テスト実行を開始するまで待ち、以前に指摘された差分が実際に解消されたことを確認します。

   # CLI (resolves from local git HEAD — already the pushed commit)
   meticulous agent test-run-for-commit
   meticulous agent test-run-diffs --onlyRejected --onlyWithComments --includeReviews
   
   # 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>", onlyRejected=true, onlyWithComments=true, includeReviews=true)
   

修正したつもりの差分がまだ表示されている場合（判断やコメントは比較対象の実行から引き継がれます）、根本原因に対処できていません。その差分についてステップ 3／4 に戻り、その後このステップを繰り返してください。

レビューは引き継がれない点に注意してください。新しい実行のチェックは未判断の状態から始まります。チェックの修正を確認するには、新しい実行でそのチェックのレポートを取得し（meticulous agent test-run-check --checkId=<checkId> [--checkType=custom]）、修正した指摘がなくなっていることを確認してください。

プロジェクトで各コミット時に Agent swarm が実行される場合、プッシュしたコミットでの実行（ステップ 1 と同様に meticulous agent agent-swarm-run を実行）を確認すれば、修正したケースがパスするようになったか分かります。caseIndex は変わることがあるため、タイトルで照合してください。新しい修正プロンプトとともに再び失敗した場合は、そのケースについてステップ 4 に戻ってください。

ステップ 6 -- 最終レポート

ステップ 1 のすべての修正対象の差分、チェック、Agent swarm の修正プロンプトについて、結果をまとめます（スキップした、無視のみの行は除きます）。言及する差分にはすべてリンクを付けます：https://app.meticulous.ai/test-runs/<testRunId>/replay-diff/<replayDiffId>?screenshot=<screenshotName>。Agent swarm の結果がある場合は、こちらもリンクします：https://app.meticulous.ai/test-runs/<testRunId>?tab=agent-swarm。

1. 修正済み：解決した差分、チェック、ケース、変更したコードの内容、対応したコメント、却下理由、修正プロンプトがあればその内容を記載します。
2. 未修正（該当する場合）：対応できなかった差分、チェック、ケースと、その理由を記載します。たとえば、コメントの要望が実現不可能、曖昧、または別の要件と矛盾していた場合です。差分については、その説明を返信／コメントとして残したことを記載します（ステップ 4）。この会話でしか見えないレポートに記載するだけでは不十分です。チェックや Agent swarm のケースについては、レポートと PR コメントが、人が確認できる唯一の記録です。人間のレビュアーが調査をやり直さずに続きを確認できるよう、具体的に記載してください。

このレポートは、ここで提出するだけでなく、PR 自体にもコメントとして投稿します（GitHub では gh pr comment <number> --body "..."、GitLab では glab mr note <id> --message "..."、Bitbucket では Teamwork Graph CLI が利用可能なら twg bitbucket pull-requests comment create --pull-request <id> --text "..." を使用します。インストール済みの場合は twg-engineering-work スキルの指示に従い、Bitbucket のトークンを求められた場合は twg setup bitbucket を一度実行します。それ以外の場合は、本文に {"content": {"raw": "..."}} を指定して POST /2.0/repositories/{workspace}/{repo_slug}/pullrequests/{id}/comments を呼び出します）。

ステップ 7 -- Meticulous にフィードバックを送る

最後のステップとして、Meticulous チームに簡潔なフィードバックを 1 件送信します。却下やコメントは作業に十分な内容でしたか。曖昧な点はありましたか。引き継ぎをよりスムーズにするには、何があるとよかったですか。

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

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