review-anvil-improve-pr

review-anvil-improve-pr

review-anvil-pr を発展させた、コードを実際に修正するプリセットです。review-anvil-pr が読み取り専用でレビューコメントを投稿するのに対し、このプリセットは実際にコードを変更します。まず PR に開始コメントを投稿し、commit_mode=per_fix でレビューのループを実行します。指定されたラウンドと適応的な追加ラウンドを通じて、修正コミットをローカルブランチに適用し、結果をプッシュして PR を更新します。その後、開始コメントをその場で編集し、統合したレポート（または失敗の概要）に置き換えます。PR のタイムラインに表示されるコメントは 1 件で、状態が 2 つあります。

生成される言語

このプリセットには、ASD-STE100 に基づく言語規約を適用してください。 内部の手順には直接的な命令形を使ってください。PR コメントには、短く能動態の平叙文を使ってください。インラインの診断には見出しを付けず、依頼する作業は Suggestions: の下に、個別に実装できる変更ごとに 1 つの箇条書きで記載してください。必須の作業は、原則として動作を表す動詞から始めてください。変更しない制約は説明文で示し、軽微な指摘には提案の文型を使い、真に未解決の選択肢については質問してください。

このスキルは、次の 6 つの手順を実行します。

1. scripts/pr-helper.sh verify-checkout [<locator>] — ロケーターを解析するか自動検出し、ローカルのチェックアウトが PR の head ブランチと一致し、クリーンな状態であることを確認します。PR の base ブランチ、作成者、マーカー UUID、レポートのパスを取得します。
2. scripts/pr-helper.sh post-start — 元の作成者に cc し、これから行う作業と、最終的な概要でコメントを編集することを説明する「開始」トップレベル PR コメントを投稿します。後で編集するためのコメント ID と開始時刻を取得します。作成者には GitHub 通知が届きます。
3. review-anvil エンジンを、ブランチと base の差分に対して commit_mode=per_fix で実行します（PR ロケーターを対象にしないでください。エンジンの「PR-target / per_fix incompatibility」ルールでこの組み合わせは禁止されています。このプリセットでは、代わりにローカルブランチを直接対象にします）。エンジンは最終的な統合レポートを report_path に書き込みます。失敗時も同様です。
4. git push — 指定されたラウンドと適応的な追加ラウンドが完了するか、早期に収束した後に 1 回だけ実行します。エンジンが失敗を報告せず、ビルド／テストのゲートが成功した場合に限り、修正コミットを PR に公開します。
5. scripts/pr-helper.sh post-update — 開始コメントを PATCH で編集し、本文を最終レポート全体（outcome=success）または失敗の概要（outcome=failure）に置き換えます。GitHub は編集時に通知しないため、作成者に再度通知は届きません。手順 2 で送られる元の cc @author 通知だけが届きます。
6. 最終レポートとコメント URL をユーザーに表示します。

入力

review-anvil-pr と同じロケーター形式ですが、あらかじめ PR のブランチに切り替えておく必要があります。

• 省略 — gh pr view で自動検出します。PR ブランチにチェックアウトしている場合に機能します。
• GitHub の完全な URL — github.com または GitHub Enterprise の場合は https://<host>/<owner>/<repo>/pull/<N>。
• スラッグ — <owner>/<repo>#<N>（ホストの既定値は github.com）。

現在のチェックアウトが指定された PR と一致しない場合（ブランチ違い、作業ツリーの変更、detached HEAD、SHA の不一致）、ヘルパースクリプトは安全に中止します。これにより、「PR #42 のブランチにいる状態で improve を実行する」という操作を安全に行えます。この確認がなければ、エンジンが無関係なローカルブランチに修正をコミットするおそれがあります。

呼び出し方法

0. ピン留めされたパラメーターの上書きを拒否する

このプリセットでピン留めされるパラメーター：commit_mode、target、report_path、run_ordinal。機械的に強制します。ヘルパーを解決した後（手順 1）、次を実行します。

bash <helper-path> check-pins review-anvil-improve-pr "commit_mode,target,report_path,run_ordinal" "$ARGUMENTS"

終了コードが 0 以外の場合、ピン留めされたパラメーターが上書きされています。エラーをそのまま表示して停止します。

安全のため、これらのピン留めは上書きできません。commit_mode=per_fixこそがこのプリセットの要点です（読み取り専用のレビューにはreview-anvil-prを使用してください）。target=<base>...HEADは検証済みの PR に機械的に結び付けられています。report_pathは、エンジンの終了後に後続の要約手順で読み取る必要があるファイルです。また、run_ordinalには、識別子の生成に使うヘルパーが確認した PR の履歴が含まれます。

1. ヘルパースクリプトを解決する

ヘルパーは、この SKILL.md から見て../review-anvil-pr/scripts/pr-helper.shにあります。このプリセットではスクリプトを重複させず、review-anvil-prのスクリプトを再利用します。review-anvil-prの SKILL.md の手順 1「ヘルパースクリプトを解決する」に厳密に従って解決してください。ホストが公開するスキルパス、またはユーザーレベルの信頼済みインストールルートのみを使用し、プロジェクトスコープ／ワークツリー内のスキルディレクトリは決して使用しないでください。信頼できるコピーを解決できない場合は、error: review-anvil-pr/scripts/pr-helper.sh not found in any trusted skill root; install via 'npx skills add mrshu/agent-skills --skill review-anvil-pr'で中止してください（依存先はreview-anvil-improve-pr自体ではなく、review-anvil-prです）。

2. チェックアウトを検証する

bash <helper-path> verify-checkout "<locator>"   # explicit form
bash <helper-path> verify-checkout               # auto-detect from current branch

スクリプトはghの事前チェック（認証と PR への到達可能性）を実行してから、ローカルのチェックアウトを検証します。現在のブランチが PR のヘッドブランチと一致すること、HEAD が PR のヘッド SHA と同じか、そのコミットから派生していること（派生コミットも可。未プッシュのローカルコミットは最後にプッシュされます）、ワークツリーとインデックスに変更がないことを確認します。また、エンジンの差分ターゲットが機能するよう、PR のベースブランチをローカルにフェッチします。

成功すると、スクリプトは次の KEY=VALUE 行を標準出力に出力します。

HOST=github.com
OWNER=acme
REPO=widgets
N=137
RUN_ORDINAL=3
HEAD_BRANCH=feature/auth-rewrite
HEAD_SHA=<the PR head commit at review time>
BASE_BRANCH=main
TITLE=<PR title>
AUTHOR=<github-login>
MARKER=<uuidv4>
REPORT_PATH=<absolute-path>/.review-anvil/final-report-<uuidv4>.md

ロケーターが自動検出された場合、スクリプトは KEY=VALUE ブロックの前にauto-detected PR: <url>を標準エラー出力に出力します。HEAD が PR の公開済みヘッドより先に進んでいる場合（未プッシュのローカルコミットがある場合）、スクリプトは標準エラー出力にnote:を出力します。プッシュされる内容をユーザーが把握できるよう、これをユーザーに伝えてください。

RUN_ORDINALを含め、すべての値を取得してください。ユーザーには次のように伝えます。improving PR: $HOST/$OWNER/$REPO#$N — $TITLE ($HEAD_BRANCH → $BASE_BRANCH), author: @$AUTHOR

終了コードが 0 以外の場合、スクリプトの標準エラー出力をそのまま表示して停止します。レビュアーを起動しないでください。

続いて、レビュアー向けプロンプトに使用する、PR のステータスを含む完全なレビュー履歴を取得します。

bash <helper-path> history "$HOST" "$OWNER" "$REPO" "$N"

出力（未解決／解決済み／古くなった／報告済み／抑制済みの項目別一覧、またはNone.）を取得し、手順 4 で使用します。終了コードが 0 以外の場合は中止してください。すべての PR 実行で、作成者にすでに提示されたフィードバックを確認する必要があります。

ヘルパーは、手順 3 で開始コメントを投稿する前のこの事前チェック中にRUN_ORDINALを解決します。そのため、未完了の現在の開始コメントが、確定済みのレビュー実行として自分自身を数えることはありません。

3. 「開始」コメントを投稿する

レビュー作業を始める前に、次を実行します。

bash <helper-path> post-start "$HOST" "$OWNER" "$REPO" "$N" "$MARKER" "$AUTHOR"

スクリプトは、次の内容を含む PR のトップレベルコメントを作成します。

• 後から必要に応じて検索できるよう、マーカー UUID を埋め込みます。
• review-anvil-improve-pr started on this PR. cc @<author>.で始めます。
• これから行う作業と、最終結果を反映するためにコメントを編集することを説明します。
• Started: <ISO-8601 UTC>のタイムスタンプを含めます。

その後、マーカーを使ってコメントを検索し（書き込み直後の読み取り遅延に備えて 1 回再試行します）、コメント ID と URL を取得して、次の KEY=VALUE 行を出力します。

COMMENT_ID=12345678
COMMENT_URL=https://github.com/acme/widgets/pull/137#issuecomment-12345678
STARTED_AT=2026-06-07T10:00:00Z

3 つすべてを取得してください。ユーザーには次のように伝えます。starting comment posted: $COMMENT_URL。@メンションにより、PR の作成者に GitHub 通知が届きます。

post-startが投稿前に失敗した場合（ネットワークの一時的な障害、gh 認証の問題など）は、中止してください。後処理は必要ありません。これとは異なる失敗ケースとして、コメント投稿後、マーカー検索でコメント ID を取得できずにスクリプトが終了する場合があります（「posted starting comment but could not recover its ID」）。この場合、PR には開始コメントがすでに存在します。実行を中止し、以下の復旧手順に従って手動でコメントを編集してください。

4. エンジンを起動する

この引数文字列を指定して review-anvil スキルを起動します（追加のユーザー引数は固定パラメーターの後に指定します。ユーザーが指定しない場合、エンジン独自の rounds: 3 のデフォルト値と、差分サイズに応じて調整される max_rounds の上限が適用されます）。

commit_mode: per_fix, target: <BASE_BRANCH>...HEAD, report_path: <REPORT_PATH>, run_ordinal: <RUN_ORDINAL>, <extra-user-args>

<BASE_BRANCH>、<REPORT_PATH>、<RUN_ORDINAL> はステップ 2 で取得します。<BASE_BRANCH>...HEAD（3 点ドットの差分）を使うと、この PR とベースの違いを生むコミットだけが対象になります。report_path を固定すると、エンジンは最終的に統合したレポートをファイルに書き込み、ステップ 6（post-update）で読み取れるようになります。

ユーザーは、観測された run_ordinal の値を上書きできません。RUN_ORDINAL が正の整数の場合、エンジンは新しい来歴 ID に対応する RUN セグメントを含めます。値が unavailable の場合、エンジンは RUN セグメントなしで ID を生成します。履歴が不完全な場合でも、実行番号を捏造してはいけません。

ステップ 2 で取得した台帳を、エンジンのレビュアープロンプトブロック PR REVIEW HISTORY として渡します。ブランチをターゲットにすると、エンジンは台帳を自動取得しないためです。レビュアーは、報告済みの未解決、解決済み、および要約のみの項目を現在の HEAD に対して再検証する必要があります。解決済みとは会話上の状態であり、修正済みである証拠ではありません。

注：PR ロケーターを target として固定しないでください。エンジンの「PR-target / per_fix incompatibility」ルールによって commit_mode=none が強制され、このプリセットの目的が損なわれます。ブランチを直接ターゲットにするのが、意図された回避策です。

ユーザーは rounds: または max_rounds: を上書きできます（デフォルトは、エンジンの rounds: 3 と差分サイズに応じて調整される max_rounds の上限です。rounds に加えて適応型のラウンドを 1～3 回実行し、max(6, rounds) を超えることはありません）。run_ordinal、commit_mode、target、report_path は上書きできません。これらは安全のために固定されており、ステップ 0 で説明したセグメントの拒否処理により、上書きの試みはブロックされます。

エンジンは複数ラウンドのループを実行し、その過程で修正グループをコミットします。完了すると、最終的に統合したレポートを <REPORT_PATH> に書き込みます。エンジンのデフォルトの再現確認パスでは、確証のない重要な指摘が修正コミットになる前に確認されます。また、ビルド／テストゲート（verify_cmd。ユーザーが指定しない場合は自動検出されます）は、各ラウンドの修正後に実行されます。レポートの「再現」と「検証」の行は、PR 作成者がプッシュされたコミットを信頼するための根拠となります。エンジンが Verification: none detected と記録した場合、その注意書きは投稿されたレポートとともに PR に引き継がれます。必須候補の再現に失敗した場合、その候補は保留となり、ループはほかの検証済み修正を含めて完了することがあります。いずれかのラウンドが失敗した場合（レビュアーが全員失敗、git コミットエラー、復元処理後にビルド／テストゲートが新たに失敗）、エンジンはループを停止して失敗を報告します。その場合は プッシュをスキップし（ステップ 5）、outcome=failure を指定して post-update を呼び出してください（ステップ 6）。これにより、最初のコメントは放置されたままにならず、失敗の概要に置き換えられます。

5. プッシュ

エンジンが実行の成功を報告した後に限り、プッシュします。成功とは、要求されたラウンドと適応的な継続がすべて完了した（または、ループが早期に収束した場合も成功とみなします）こと、ラウンドのサマリーに git commit failed または all reviewers failed のエラーがないこと、そして各ラウンドの検証状態がすべて次のいずれかであることを指します：passed、failed → round reverted、pre-existing failures (no new)、none detected、skipped。つまり、新たに失敗状態になっていないことが条件です（これらはエンジンが使用するラウンドサマリーの状態です）。再現を保留している候補だけではプッシュを妨げません。また、それらによって修正コミットや対応が必要な PR コメントが作成されることもありません。

git push origin "$HEAD_BRANCH"

エンジンの実行が部分的な状態または失敗に終わった場合は、プッシュしないでください。手順 6 に進み、outcome=failure を指定してください。<REPORT_PATH> のレポートファイルには、失敗の詳細を含むエンジンの最終状態が記録されており、post-update はこれを使ってコメントを作成します。

エンジンの実行には成功したものの、git push が失敗した場合（権限拒否、競合など）、修正コミットはローカルに存在しますが、PR には反映されていません。それでも手順 6 を呼び出し、実際の状態がコメントに反映されるよう outcome=failure を指定してください。調査できるよう、ローカルのコミットは <HEAD_BRANCH> に残っていることをユーザーに伝えてください。

6. 最終サマリーでコメントを更新する

手順 4／5 の結果にかかわらず、この手順は必ず実行してください。エンジンとプッシュの両方が問題なく完了した場合に限り、outcome=success を渡します。

bash <helper-path> post-update "$HOST" "$OWNER" "$REPO" "$N" "$COMMENT_ID" "$MARKER" "$REPORT_PATH" "$AUTHOR" "$OUTCOME" "$STARTED_AT"

success の場合、ヘルパーはコメントを編集する前に、過去のフィードバックの記録全体を必ず再取得します。検索に失敗した場合、または再取得した履歴によって簡潔なレポートに含まれる指摘の一覧が変わった場合は、更新を outcome=failure に切り替え、その理由を説明します。フィルタリングされていないレポートや、内部的に古い成功レポートを公開することはなく、「開始中」のコメントが残ったままになることも避けます。更新に成功した後、成果物の head_sha（エンジンが最後に受け入れた修正コミット後のローカル HEAD）がプッシュ済み PR の最新の head と一致し、最新のオープンなルートコメントに対応する終端の review-anvil マーカーがある場合に限り、<REPORT_PATH>.resolutions.json の項目を解決済みにします。修正済みまたは古い指摘は解決済みにでき、受け入れられた作成者の説明についても、PR 作成者からの返信が最新のものである場合に限り解決済みにできます。人間が作成したスレッドや anvil 以外のスレッドは解決しません。

改善ワークフローでは、GitHub のインラインレビューコメントを公開できません。更新に成功し、過去のフィードバックの再取得にも問題がなかった場合、ヘルパーは処理したすべてのインラインコメントの本文を、1 つの折りたたまれた Finding details セクションに追加します。表示されるレポートは、見出しのない中立的な検出文 1～2 文のみです。一方、折りたたまれた詳細テーブルと指摘の詳細には、診断内容と依頼された作業がすべて保持されます。失敗時の更新では、再取得を省略または失敗したインラインコメントの本文を追加しません。それ以外の場合、ヘルパーはレポート本文を短縮せずに投稿します。GitHub が通常より大きいペイロードを拒否した場合、更新は明確に失敗し、レポート成果物はそのまま残ります。実行中のエージェントは、同じ指摘、根拠、実行可能な詳細を保ちながらレポートをより整理された形式に書き直し、更新を再試行してください。

$OUTCOME は success または failure です。このスクリプトは $COMMENT_ID で特定した開始コメントを PATCH で編集します。成功時の更新には、非表示マーカーと簡潔なレポートのみが含まれるため、既定の表示は見出しのない中立的な検出文 1 行のままで、末尾には review-anvil のフッターが残ります。完了状態、作成者へのメンション、開始時刻と完了時刻、結果は、折りたたまれた Review context 内に残ります。失敗時の更新では、失敗レポートの前に review-anvil-improve-pr failed という文を 1 つ表示できます。配信メタデータは折りたたまれたままです。

GitHub はコメントの編集時に通知しないため、作成者に再通知は届きません。手順 3 で送信した最初の cc @author 通知のみが通知されます。

成功時の post-update を呼び出す前に、<REPORT_PATH>.followups.json が存在する場合はその内容を読み取り、ユーザーに提示してください（スクリプトはその後、このファイルを削除します）。スクリプトは一時的なレポート成果物 5 つ（<REPORT_PATH>、.inline.json、.resolutions.json、.approval.json、.followups.json）をクリーンアップし、他にレポート成果物が残っていなければ、自己除外されている .review-anvil/ ディレクトリも削除します。配信に成功してもスレッドの解決に失敗した場合は、.resolutions.json を保持します。次のコマンドで再試行してください。bash <helper-path> resolve "$HOST" "$OWNER" "$REPO" "$N" "<resolutions-path>"。保持される証拠バンドルは、ホストが作成した別のプライベートディレクトリにあり、ワークツリーの外に置かれます。内容は変更されません。

post-update 自体が失敗した場合（まれな例として、一時的な gh の問題や、実行中にコメントが手動で削除された場合）は、エラーをユーザーに伝えます。ただし、プッシュを取り消してはいけません。修正コミットはすでに PR に反映されており、コメントの編集漏れは復旧可能です。ユーザーはコメント ID を使って開始コメントを手動で編集できます。その場合に備えてレポートファイルはディスク上に残ります（post-update の失敗時はクリーンアップされません）。

7. 結果を報告する

エンジンの最終レポートをそのまま表示します。2 行の要約を出力します。

• pushed N commits to $HOST/$OWNER/$REPO#$N ($HEAD_BRANCH)。N には、プッシュした修正コミット数、または最終レポートの折りたたまれた Changes made リストの件数を指定します。ステップ 5 がスキップされた場合（失敗時）は、代わりに did not push (engine/run failure) と記載します。
• comment $COMMENT_URL updated with outcome=$OUTCOME（または、ステップ 6 でエラーが発生した場合は comment update failed: ...）。

例

• 「今作業している PR を改善して」 — ユーザーは PR ブランチをチェックアウト済みです。エージェントはロケーターを指定せずに verify-checkout を呼び出し、ヘルパーが自動検出します。
• 「acme/widgets#137 で 5 ラウンド実行して」 — ユーザーがスラッグを指定し、ラウンド数を増やすよう依頼しています。エンジンのデフォルト値は、末尾の rounds: 5 引数によって上書きされます。
• 「本番環境の安全性に重点を置いて、この PR をレビューして改善して」 — ユーザーがデフォルト以外の観点を指定しています。これは focus: production blast-radius（または同様の値）としてエンジンに渡されます。

制約

• gh、uuidgen、jq（実際のバイナリ。gh に組み込まれている --jq は gojq であり、要件を満たしません）、および PR フィードバック履歴の処理に使う uv（推奨。ない場合は python3 にフォールバック）が必要です。verify-checkout はこれらすべてを事前チェックするため、依存関係が不足している場合は、時間のかかるレビューを開始する前に失敗します。このヘルパーは review-anvil-pr と同じ環境スイッチ（REVIEW_ANVIL_NO_APPROVE、旧名の REVIEW_ANVIL_SKIP_DISMISSED、REVIEW_ANVIL_DISMISSALS）に対応します。
• ローカルの作業ツリーを変更し、PR にプッシュします。 修正を適用せずにフィードバックだけが必要な場合は、review-anvil-pr（読み取り専用＋コメント）を使用してください。
• ユーザーはすでに PR のブランチにいて、作業ツリーがクリーンである必要があります。verify-checkout ステップはこれを確認し、失敗した場合は明確な復旧手順（例：gh pr checkout <N>）を提示します。
• PR へのプッシュ権限が必要です。権限がない場合、git push は通常の git エラーで失敗します。スクリプトはプッシュ権限を事前確認しません。
• github.com と GitHub Enterprise に対応します。処理方法は review-anvil-pr と同じです。

復旧：放置された「starting」コメント

オーケストレーターがクラッシュした場合（またはエージェントホストがコンテキストを失った場合、あるいはユーザーが中断した場合）、ステップ 3 とステップ 6 の間に PR 上に「starting」コメントが残り、実行されない編集を約束した状態になります。クラッシュしたタイミングによっては、修正コミットがプッシュ済みの場合と未プッシュの場合があります。

これはまれですが、復旧できます。放置された starting コメントを見つけた場合：

1. PR 上でコメントの URL を確認します。本文は `` と review-anvil-improve-pr started on this PR. で始まります。数値のコメント ID は URL の末尾（...#issuecomment-<ID>）にあります。
2. gh api でコメントを手動編集します。

   gh api repos/<owner>/<repo>/issues/comments/<COMMENT_ID> -X PATCH \
     -F body="review-anvil-improve-pr failed: orchestrator did not complete. No reliable summary available."
   

   または、GitHub の Web UI でコメントの「編集」メニューを使用します。

オーケストレーターがまだ動作していて、エンジンは完了したものの何らかの理由でステップ 6 がスキップされた場合、レポートはステップ 4 で表示されたパスにまだ保存されています。内容をそのまま編集本文に貼り付けられます。

エンジンが実行されなかった場合（ステップ 3 とステップ 4 の間でクラッシュした場合）、何もプッシュされていません。上記のように、コメントを「did not complete」という内容に編集してください。

組み合わせて使うもの

review-anvil エンジンと review-anvil-pr プリセット（このスキルが scripts/pr-helper.sh を再利用します）に依存します。3 つとも同じプラグインに含まれており、まとめてインストールしてください（npx skills add mrshu/agent-skills --skill review-anvil --skill review-anvil-pr --skill review-anvil-improve-pr、または --all のみ）。