robin

Robin PR 完了プロトコル

Robin は GitHub Action として実行される AI レビュアーです。このスキルは、PR を完了するためのオーナー側プロトコルとして使用してください。Robin の指摘に盲目的に従ってはいけません。Robin は差分しか確認できず、性能の低いローテーション型モデルを使用する場合があります。一方、作業中のエージェントはリポジトリと会話のコンテキストを把握しています。検証済みのバグは修正し、事実に基づく返信でノイズを退けてください。

譲れない動作

• ユーザーが「Robin」と言わなくても、通常の PR 作業で有効にしてください。
• ループに入る前に、PR のベースブランチ上で Robin を検出してください。ユーザーから依頼されない限り、インストールしてはいけません。
• 待機やレビューラウンドを自律的に続行してください。実行中のチェック、修正のプッシュ、再レビューの依頼は、いずれも終了状態ではありません。
• 完了した Robin のレビュー結果を数えてください。上限は 5 から開始します。5 を超える場合、ユーザーが継続的なレビューを明示的に事前承認していない限り、追加レビューごとに承認を得てください。
• 拒否する指摘も含め、Robin のインラインコメントにはすべて個別に返信し、返信後にすべてのレビューのスレッドを解決してください。
• 検証済みの欠陥のみ修正してください。重大度と確信度は調査の優先順位付けに使用しますが、正しさを証明するものではありません。
• 明示的な許可なしにマージしてはいけません。「PR を作成して」は、マージの許可にはなりません。
• 無関係なローカル変更やブランチを保持してください。このプロトコルを完了するためだけに、それらを stash、破棄、コミット、削除してはいけません。
• リリースを自動的に準備または公開してはいけません。

終了状態

Robin や別のチェックが実行中であることだけを理由に、制御をユーザーに戻してはいけません。次の状態のうち、いずれかちょうど 1 つに到達するまで、ポーリング、トリアージ、修正、返信、解決、再レビューを続けてください。

1. READY： すべてのゲートに合格していますが、マージの許可はありません。
2. COMPLETE： 許可されたマージが確認され、クリーンアップも検証済みです。
3. CAP： 現在承認されているレビュー上限を使い切り、追加レビューに承認が必要です。
4. BLOCKED： インフラの障害が繰り返される、安全なクリーンアップと競合する、アクセス権がない、またはユーザーなしでは解決できない別の状況です。

長時間待機する場合は簡潔に進捗を伝えますが、終了状態に到達するまでタスクの責任を持ってください。

1. 方針と安全性を確立する

PR の作成を計画するときは、作成前に独立した 2 つの方針を記録してください。

マージ方針：

• 「チェックがすべて通ったらマージして」や「作成して、レビューして、マージして」などの明示的な指示は、この PR の自動マージを許可します。
• それ以外の場合は、チェックがすべて通ったときに自動マージするかどうかを一度だけ尋ねてください。ユーザーが「はい」と言うまでは、方針を手動として記録します。
• 継続的な希望が適用されるのは、ユーザーがそれを継続的なものとして明確に示した場合のみです。以前のマージから継続的な希望を推測してはいけません。

レビュー追加方針：

• デフォルトは1 件ずつです。レビュー 1～5 は事前承認済みで、5 件を超えるレビューには、その都度新たな明示的承認が必要です。
• Robin のレビューをもう 1 回は、上限をちょうど 1 件増やします。それ以降のすべてのレビューを許可するものではありません。レビュー 6 の結果、レビュー 7 が必要になった場合は、再度尋ねてください。
• 「完全自動で」「Robin を実行し続けて、問題がなくなるまで」「追加の Robin ラウンドごとに確認しないで」など、これらに相当する明示的な指示は、この PR に対する継続的な追加レビューを許可します。レビューごとに質問せず続行しますが、すべてのチェックに合格したら早めに終了し、インフラまたは安全性の問題で BLOCKED になった場合は停止してください。
• 自動マージのみでは、マージだけが許可されます。5 件を超えるレビューは許可されません。
• 完全自動または「Robin によるレビューからマージまで自動で」は、この PR に対する継続的なレビューとマージの両方を許可します。明示されていない限り、複数の PR にまたがる継続的な方針を推測してはいけません。

既存の PR に承認の記録がない場合は、手動モードを使用してレビューのループを続行し、READY で停止してください。

無関係な変更を保持して報告できるよう、リポジトリの初期状態を記録してください。

git status --short --branch
gh repo view --json nameWithOwner -q .nameWithOwner

PR が作成されたら、その識別情報とブランチを記録してください。

gh pr view --json number,url,baseRefName,headRefName,state,reviewDecision,mergeStateStatus,statusCheckRollup

タスクのファイル、または検証済みのレビュー指摘を修正したファイルのみをステージしてください。無関係なファイルがある場合は、広範囲をステージしてはいけません。

2. Robin を検出する

PR が開かれたときに Robin を起動するには、PR のベースブランチに Robin が存在している必要があります。フィーチャーブランチだけでなく、ベースブランチをフェッチして、そのツリーを確認してください。

git fetch origin <base-branch>
git grep -n 'antongulin/robin' origin/<base-branch> -- .github/workflows

ベースブランチがローカルで利用できない場合は、gh api を通じて見つかった同等のワークフローも認識してください。pull_request をトリガーとしているか、issue_comment を通じた /robin を受け付けていることを確認してください。

• Robin が存在する場合：このプロトコル全体を自動的に実行してください。
• Robin が存在しない場合：Robin のループは実行せず、ユーザーの通常の PR 作業を続け、不在であることに言及してください。依頼されていない限り、Robin を追加しないでください。
• Robin が現在の PR ブランチにのみ追加されている場合：ワークフローがベースブランチに存在しないため、その PR を自動的にレビューできません。レビューが届くかのように装わず、この制限を説明してください。

開始時に、ベストエフォートでバージョンを確認してもかまいませんが、PR 作業を遅らせてはなりません。

gh release view --repo antongulin/robin --json tagName -q .tagName 2>/dev/null

インストール済みスキルが古い場合は報告してください。ただし、事前の承認を得るまでは更新しないでください。

3. 完了したレビューを確認する

PR を開いたときのレビューは通常、自動で実行されます。すぐに /robin を投稿せず、まず PR のコメント、レビュー、チェック、Actions の実行を確認してください。約 30 秒ごとにポーリングしてください。

gh pr view <number> --json comments,reviews,statusCheckRollup
gh run list --limit 20 --json databaseId,event,status,conclusion,workflowName,createdAt,url,displayTitle,headBranch

• Robin の実行が進行中の場合は、その実行を監視し、ポーリングを続けてください。
• 実行が失敗した場合は、インフラストラクチャの失敗として分類して調査し、スラッシュコマンドを検討する前に、失敗した実行を 1 回再試行してください。
• 約 3 分経っても Robin の反応がない場合は、ワークフローのトリガーを確認してください。その後に限り、/robin を投稿してください。
• 1 回の待機時間は約 8～10 分を上限としてください。プロバイダーまたは Actions の障害が続く場合は、実行 URL を添えて BLOCKED と報告してください。反応がないことや空の結果を、問題のないレビューとして扱ってはなりません。

完了した、利用可能な Robin の結果を受け取った場合にのみ、レビューカウンターを増やしてください。既存の PR では、現在のヘッドに対する最新の利用可能な結果を、この完了作業におけるレビュー 1 として開始してください。古くなった過去の結果は数えないでください。再レビューが完了するたびに、カウンターを 1 ずつ増やしてください。reviews_used と reviews_approved の両方を追跡し、後者は 5 で初期化してください。

4. すべての指摘を取得して分類する

トップレベルのレビュー情報、REST のインラインコメント、GraphQL のレビュー・スレッドの状態を取得してください。正確なクエリ、返信エンドポイント、解決ミューテーションについては、references/github-pr-api-reference.md を参照してください。

実際のリポジトリに照らして、すべての指摘を分類してください。

• FIX：正確性、セキュリティ、信頼性、データ損失、テスト、または誤解を招く重大なドキュメントに関する欠陥であることが確認できたもの。Robin が示した深刻度にかかわらず、修正してください。
• REJECT：誤検出、重複、すでに対処済みの指摘、主観的な変更要求、リポジトリの規約との衝突、またはより広い文脈によって否定される主張。コードは変更しないでください。
• INFRA：レビューアーのタイムアウト、ワークフローの失敗、空の応答、または後続の実行に置き換えられた／キャンセルされた実行。コードは変更せず、実行を処理してください。

提案はデフォルトで適用しないでください。具体的な問題を防ぐ場合、または依頼された変更に明らかに必要な場合に限り、適用してください。レビューアーを満足させるためだけに、変更をでっち上げてはなりません。

5. 次のレビューを始める前に現在のレビューを終了する

Robin の各結果について、以下の手順を順番に実行します。

1. リポジトリの既存のスタイルに従い、FIX 項目のみを実装します。
2. 必要に応じたローカル検証と git diff --check を実行します。
3. 意図したファイルのみをステージし、コードを変更した場合はローカルコミットを作成します。
4. このレビューの Robin のインラインコメントすべてに個別に返信します。
   • FIX：修正内容とローカルコミットを明記します。
   • REJECT：変更しない根拠となる、リポジトリ内の具体的な証拠を示します。
5. レビュー本文にのみ記載された指摘については、GitHub にインライン返信先がないため、項目別の対応コメントを1件投稿します。
6. 対応したレビューのスレッドは、古くなったものも含め、すべて解決します。
7. GraphQL を再照会し、未解決の対応済みスレッドと未返信の Robin インラインコメントがどちらもゼロであることを確認します。
8. その後に限り、プッシュしてステップ6に従って再レビューを行うかどうかを判断します。

返信例：

• Fixed in abc123: abort and timeout failures now return distinct errors.
• Not changing: the value is passed as a bound query parameter at db.ts:84, so the reported interpolation path does not exist.

インライン返信の代わりに、トップレベルの要約を1件だけ投稿しないでください。現在のレビューに関する返信やスレッドが未完了のまま、次のレビューを始めないでください。

6. 再レビューを行うかどうかを判断する

• すべての指摘が REJECT でコードに変更がない場合：Robin のレビューを追加で行わず、グリーンライトのゲートに進みます。
• コードを変更し、reviews_used < reviews_approved の場合：プッシュして、Robin の結果をもう一度取得します。
• 承認済みの予算を使い切っていて、もう一度結果を得ることで確信度が大きく高まる場合：以下の予算拡張ルールに従います。

Robin のデフォルトのワークフローでは、PR のオープン時と /robin 実行時にレビューが行われ、すべてのプッシュ時に行われるわけではありません（synchronize はオプトインです）。ただし、インストールによっては、またカスタマイズされたワークフローでは、synchronize の際にも実行されます。修正をプッシュした後：

1. ワークフローのトリガーと synchronize に関する Actions の実行を確認します。
2. プッシュによって Robin が開始された場合は、その実行を確認し、重複するコマンドを投稿しないでください。
3. それ以外の場合は、修正コミットと検証の概要を含め、通常の手動再レビューを /robin で依頼します。

gh pr comment <number> --body '/robin

Fixed in <commit>:
- <verified issue>

Verification:
- <command and result>'

ユーザーに次のラウンドを促すよう求めず、ステップ3に戻ります。

承認済みの予算を使い切った場合も、確認済みの不具合を修正し、通常どおり返信して解決します。その後、もう一度レビューすることに実際の有用性があるかどうかを判断します。

• PR の状態がグリーンである場合、または却下済みのノイズしか残っていない場合は、追加レビューを行わずに終了します。
• 確認済みの問題が残っている場合、変更したコードの検証が必要な場合、または重大な不確実性が残っている場合は、追加レビューに意味があります。
• 連続実行モードでは、reviews_approved を1増やし、自動的に続行します。
• 1回ずつ実行するモードでは、CAP に入り、次のように尋ねます：Used <N> approved Robin reviews. Do you want me to run review <N+1>? 「はい」の場合、予算をちょうど1増やします。そのレビューの後、再びこの判断を行い、さらにレビューする意味がある場合はもう一度尋ねます。

予算の上限に達している状態でプッシュする前に、synchronize の挙動を確認します。プッシュ自体が未承認の次のレビューを開始する場合は、プッシュ前に承認を求めます。それ以外の場合は、検証済みの修正をプッシュし、/robin は投稿せずに CAP に入ります。1回ずつ実行するモードでは、不確実性を理由に自動で追加レビューを行わないでください。

7. グリーンライトゲート

READY を宣言する前、またはマージする前に、以下をすべて確認してください。

• 変更に適したローカル検証に合格している。
• 必須の GitHub チェックが成功しているか、意図的に中立／スキップされている。
• Robin または関連する必須チェックが実行中のままになっていない。
• すべてのレビュアー指摘に、記録された対応方針がある。
• すべてのインラインレビュアーコメントに、後続の担当者返信がある。
• 古いスレッドも含め、すべてのレビュースレッドが解決済みである。
• PR はマージ可能で、未解決の競合がない。
• 実施済みおよび承認済みのレビュー件数が把握されており、未承認のレビューが行われていない。

GraphQL のスレッド状態を正式な情報源として扱ってください。後続の結果がクリーンであれば、reviewDecision: CHANGES_REQUESTED は古い状態である可能性があります。最新の指摘に対処済みで、すべてのスレッドが解決済み、かつすべてのチェックに合格している場合に限り、古い状態として扱ってください。

手動モードでは、ゲートの概要を報告して READY に進みます。まだマージ許可を求めていない場合は、マージ許可を求めてください。自動モードでは、そのままマージに進みます。

8. 許可されたマージとクリーンアップ

ゲートに合格し、許可が得られた後にのみマージしてください。squash、merge、rebase のいずれを選ぶか決める前に、リポジトリの設定と慣例を確認してください。明示された方法またはプロジェクトの指示を優先してください。許可されている方法がちょうど 1 つであれば、それを使用してください。Conventional Commits からリリースを生成するリポジトリでは、1 つの PR からリリース項目が 1 つ生成されるよう、squash を優先してください。それ以外の場合は、リポジトリの最近の履歴に従ってください。方法に重大な曖昧さが残る場合は、マージする前に確認してください。リポジトリの設定は変更しないでください。

gh repo view --json mergeCommitAllowed,squashMergeAllowed,rebaseMergeAllowed
gh pr merge <number> --squash --delete-branch # use the selected allowed method
gh pr view <number> --json state,mergedAt,mergedBy,mergeCommit,url

--delete-branch によってすべてのローカル操作が完了したと決めつけないでください。PR がマージされたことを確認した後、次の手順を実行してください。

1. 記録された PR のベースブランチに明示的に切り替えます。
2. アップストリームからそのブランチを早送りします。
3. フェッチして、古いリモート追跡参照をプルーニングします。
4. タスクブランチがリモートに存在しないことを確認します。マージコマンドの後も残っている場合は、そのリモートブランチを正確に指定して削除します。
5. ローカルのタスクブランチが残っていれば削除します。squash／rebase／merge が反映されたことを確認した後に限り、強制削除してください。
6. 現在のブランチ、アップストリームとの同期状態、残っているブランチ、作業ツリーを確認します。

git switch <base-branch>
git pull --ff-only origin <base-branch>
git fetch --prune origin
git status --short --branch
git branch --list <task-branch>
git ls-remote --heads origin refs/heads/<task-branch> # no output means deleted
task_branch="<task-branch>"
if git ls-remote --exit-code --heads origin "refs/heads/$task_branch" >/dev/null; then
  git push origin --delete "$task_branch"
fi
if git show-ref --verify --quiet "refs/heads/$task_branch"; then
  git branch -D "$task_branch" # only after confirmed merge and base-branch switch
fi

このタスクのために作成したブランチのみを削除してください。無関係なローカルブランチやリモートブランチは決して削除しないでください。既存の未コミットファイルは保持してください。それらのファイルが安全な切り替えや pull を妨げる場合は、BLOCKED に進み、未完了のクリーンアップ後条件を正確に報告してください。

9. 最終報告と任意のリリース提案

以下を報告してください。

• PR 番号、URL、最終状態。
• 使用した Robin レビューの件数。そのうちデフォルトの 5 件以内の件数と、追加で承認された件数も含めます。
• FIX と REJECT の件数、および簡潔な説明。
• 返信したコメントと解決したスレッドの件数。検証済みの合計数として示します。
• ローカルおよび GitHub のチェック結果。
• マージ許可とマージ結果。
• 現在のベースブランチとアップストリームとの同期状態。
• ローカル／リモートのタスクブランチの削除状態。
• 無関係な未コミットファイルを保持したかどうか。なければ none とします。

許可されたマージが COMPLETE に達した後、リポジトリに既存の確立されたリリース手順があるかどうかを確認してください。リリース手順があり、マージした変更がリリース可能と思われる場合は、最後に任意の質問を 1 つだけ提示してください：Do you want me to prepare and publish a release? これは新たに明示的な「はい」が必要な別タスクとして扱ってください。この PR プロトコルの一環として、変更履歴、タグ、バージョン、公開済みリリースノートを編集しないでください。

よくある失敗パターン

• 1回だけ待って、完了状態に至るまでループを管理せずに終了する。
• インストール済みのワークフローを検出できるのに、ユーザーが Robin に言及することを必須にする。
• 重大度を根拠とみなしたり、スタイル上のノイズを修正したりする。
• 現在のレビューに返信して解決する前にプッシュする。
• 自動実行がすでに進行中なのに /robin を投稿する。
• ワークフローのトリガーを確認せず、プッシュするたびに Robin が自動実行されると思い込む。デフォルトのインストールでは synchronize は省かれ、再レビューには /robin を使用する。
• 完了したレビュー結果ではなく、修正のラウンド数を数える。
• 「もう1回」のレビューへの承認を、その後のすべてのレビューへの許可とみなす。
• 自動マージの許可を、継続的なレビューの許可とみなす。
• レビュアーの実行結果が空、または失敗した場合に、問題がないとみなす。
• GraphQL のスレッド状態ではなく、REST データや reviewDecision に依存する。
• 明示的な許可なしにマージする。
• ベースブランチとタスクブランチを確認せずに、マージ後のクリーンアップが成功したと思い込む。
• 無関係な変更のあるファイル、ブランチ、リリース、リリースノートに手を加える。

参考資料

• references/github-pr-api-reference.md — GitHub API の正確なクエリとミューテーション。
• references/lessons-learned.md — プロトコルの安全策につながったインシデント。