update-pr reference

update-pr は、既存 PR のタイトルと本文を現在の base…HEAD、検証、CI、review、E2E の状態に合わせて更新する skill である。 古い本文へ経緯を追記するのではなく、初見の reviewer が今の変更だけを判断できる説明へ整える。

使いどころ

• 追加 commit 後に PR 本文を現在の差分へ合わせたい
• CI、review、E2E、手元検証の確定結果を反映したい
• PR タイトル、本文、または両方を更新したい
• PR 作成後の暫定表現や古い説明を解消したい

PR URL または番号を指定できる。 指定がなければ現在 branch に対応する PR を探し、見つからなければ更新せず停止する。

まず何が起きるか

1. PR の current title、本文、base、head、diff、commit、linked Issue を取得し、現本文をファイルへ保存する。コミット履歴は baseRefName で実 base branch を特定し、git fetch origin "$base" 後の "origin/$base"..HEAD を基準にする。
2. GitHub 上の CI、現在セッションの検証、review、E2E から確認済みの実結果を集める。
3. 保存した current body を確認し、base…HEAD の最終差分を基準にタイトルと本文の提案を作る。
4. 本文の読みやすさ、証跡、Issue との重複、内部運用語の混入を検査する。
5. 必要な場合だけ本文 reviewer の指摘を反映し、再検査する。
6. 更新 scope と許可を確認し、review-orchestrator pr-publication update を実行する。baseline がない場合や外部編集がある場合は、差分と具体案を提示してユーザー選択を待つ。
7. GitHub から current title と本文を読み直し、更新結果を報告する。

gh pr edit は直接使わない。 更新前に PR が別の操作で変わっていた場合は、その内容を上書きせず最新状態の読み直しへ戻る。

本文起草の実行経路

本文の内容契約は共通だが、起草方法は runtime ごとに異なる。Claude runtime は pr-materials.v1 を作り、子 process の compose-body を既定で呼ぶ。

status: adopted なら body_path を採用する。preservation_reason: narrative_limits_unresolved が残っても、最後の本文と観測結果を使って続行する。status: inline_fallback なら fallback_reason を残し、既存の inline 起草と 1 パス検査へ進む。

Codex / Copilot / Gemini runtime は現行の inline 起草と 1 パス検査を維持する。reviewer gate はどちらの経路でも compose-body の外側に置く。

narrative 上限観測は auto の本文 reviewer を起動する合図になる。削除できる重複や時系列記述、Issue の再掲が残る場合は本文を直し、数値超過だけなら、超過しても残す文と判断材料を理由に明記して proceed する。検証・E2E 欄の証跡量はこの圧縮判断の対象にしない。

本文の更新方針

利用者が追記や局所修正を明示していない限り、本文全体を現在の最終差分から組み直す。 レビュー指摘への対応や以前の方式など、実装中の時系列は残さない。

再構成の前に保存した current body を確認し、古い原稿からユーザーによる追加・修正・削除を黙って落とさない。 通常の create / update 成功時に公開した本文を PR ごとの永続 baseline として使う。 baseline との比較は update が返す body_update_review を正本とする。

• 変更前の問題、変更後の状態、判断理由を本文単体で読めるようにする。
• linked Issue の背景は必要な分だけ使い、Issue 全文を順番に言い換えない。
• narrative の先頭の背景枠は課題と実現した状態を合計2〜3文、300字以内でまとめ、背景枠を除く narrative の説明も合計300字以内に収める。2 種類の 300 字上限は別々に守る。
• 互換性リスクと review focus は、書くべき内容がある時だけ各 1 文で書き、該当がなければ書かない。
• Closes #N / Fixes #N と 実装イメージ: [design doc](URL) 形式の Design doc link は、現在の実装対象に合うものだけ保持する。
• stale な将来形 status は、取得できた実結果または理由付き未確認へ更新する。
• e2e=final などの内部 workflow 用語は、対象自体を説明する場合を除き reviewer 向けの表現へ置き換える。

GitHub に投稿する PR 本文の inline code は Markdown の backtick を使い、raw HTML の <code>...</code> は生成しない。 日本語のタイトルと本文は Public Wording Guard、why-led、readability gate に加えて stop-ai-slop-jp の観点でも確認する。

検証と証跡

更新時に参照できるのは、GitHub から取得した current state、現在セッションで実行した command、review / E2E の証跡、利用者が明示した結果である。 取得できない結果を推測して成功済みと書かない。

• 実行済みの command は command、終了状態、結果が分かる transcript を載せる。
• E2E は実施内容、結果、log、screenshot、run URL のいずれかを載せる。要約だけで成功扱いにしない。
• E2E を実施していない場合は、同じ行に理由を書く。
• UI 変更の before / after 画像は折りたたまず、reviewer が比較できる位置に置く。
• local path だけの証跡は公開せず、本文内の transcript または GitHub から読める link に変換する。

小さな text artifact は本文へ埋め込み、画像、binary、大きな text は公開用 URL へ変換する。 artifact の公開で PR branch の diff は変更しない。

更新 scope と許可

案の提示、preview、確認だけを求められた場合は、PR を更新しない。 現在の依頼から対象 PR と更新範囲が一意なら、生成内容の品質検査と提示後に同じ更新可否を再質問せず進める。

親 workflow から呼ばれた場合も、同じ PR、更新範囲、mutation を許可する指示が必要である。 scope、公開 API、設定形式、画面上の挙動に重要な未確定事項がある場合や、破壊的操作、承認 bypass、force push、秘匿情報の露出につながる場合は更新前に停止する。

外部編集がある場合

baseline がない場合、または現本文に baseline からの外部追加・修正・削除がある場合は、PR を更新せず status=needs_user_decision、next_required_action=choose_body_update と body_update_review を返す。 本文更新の依頼だけでは、外部編集の上書きやマージを選んだことにはならない。

body_update_review には id、baseline_known、baseline_body、current_body、proposed_body、merged_body、user_diff、proposal_diff、merge_available、merge_reason、choices が含まれる。 差分と具体案を確認して、次の操作を選ぶ。

選択後だけ、同じ body-file と update 引数に –body-update-choice overwrite|merge|cancel --body-update-review-id <id> を追加して再実行する。 選択待ちの間は提案本文ファイルと返却 JSON を保持し、merge でも body-file をマージ案へ差し替えない。 無人実行で未回答なら保留する。

選択は PR、HEAD、baseline、current、proposal、title に結び付く。どれかが変わった場合やマージ不能の場合は、差分と具体案を再提示して再選択する。 ObservedCurrentDigest の再取得だけで上書きを承認しない。選択後も本文検査、reviewer、effect replay、expected HEAD の guard は維持する。

cancel は status=cancelled、decision=cancel_body_update、next_required_action=none を返す。 公開成功として扱わず、本文と baseline を変更しない。title-only 更新でも本文と baseline を変更しない。

公開結果

更新後は GitHub 上の current title と本文を確認し、反映した検証、CI、review、E2E の状態を報告する。 PR 本文には最新の実行 runtime を示す AI attribution フッターを自動付与し、正規の 1 block だけを残す。

PR 作成後に review / CI / E2E の結果で本文を変える場合は、update-pr skill を経由し、skill の外から review-orchestrator pr-publication update --body-file を直接実行しない。title-only 更新と、create-pr ステップ7 / update-pr フェーズ8 の body_findings[] 修正に伴う同一 body の再実行は例外とする。

linked Issue workflow が追加 commit 後も続く場合は、呼び出し元が PR と current HEAD の結び付きを更新する。 この skill は host profile 専用の section、marker、label を本文へ追加しない。

停止後の対応

• 対象 PR が見つからない、または更新 scope を一意に決められない場合は、PR と範囲を確認する。
• 本文検査で未解消の finding が残る場合は、本文を直して再検査する。修正 round の上限に達した場合は更新せず報告する。
• 指定した本文 reviewer を開始できない場合は、別 reviewer へ黙って変更しない。利用可能な transport と許可を確認する。
• 必要な検証や E2E 証跡が欠ける、または current HEAD と一致しない場合は、再実行か理由付き未実施へ戻す。
• 更新直前に GitHub 上の本文が変わった場合は、最新本文を読み直して案を作り直す。
• 更新 request 後の確認に失敗した場合は、GitHub の current state を取得し、反映済みか未反映かを確定してから再開する。

失敗時に gh pr edit を直接呼んで guard を回避しない。 複数行本文は shell の inline 引数へ埋め込まず、安全な本文ファイルとして渡す。

Related Docs

• create-pr reference
• Issue workflow skill guide
• claude/skills/update-pr/SKILL.md
• 本文差分の提示と選択
• claude/skills/create-pr/references/pr-writing-guidelines.md
• claude/skills/create-pr/references/pr-body-reformat-gate.md

手順の参照先

本文と証跡の規則は create-pr と共通の pr-writing-guidelines.md を使う。更新範囲と外部編集の扱いは body-update-choice.md に従い、reviewer の実行・復旧は pr-writing-review-adapters.md を参照する。