create-pr reference

create-pr は、現在の差分を初見の reviewer が判断できるタイトルと本文にまとめ、GitHub に PR を作成する skill である。 ファイルや commit の列挙ではなく、変更前の問題、変更後の状態、判断理由、検証結果を先に伝える。

使いどころ

  • PR または Draft PR を作成したい
  • Issue 実装 workflow の pr=create / pr=draft で公開まで進めたい
  • push 済みの branch から、reviewer 向けの本文を整えて PR を作りたい

PR 作成を伴う依頼ではこの skill を使う。 gh pr create --fill で commit だけから本文を埋めない。

指定 意味
pr=create 通常 PR を作成する
pr=draft / --draft Draft PR を作成する
stack=<PR number&#124;PR URL&#124;auto> / stack=true 親 PR を直接、または linked Issue の依存から解決する
stack-base=<branch> 指定した branch を base にし、その branch の open PR を親として stack を連結する
pr-writing-review=auto 本文検査で確認が必要な時だけ、実行 runtime の reviewer gate を使う
pr-writing-review=codex / pr-writing-review=claude / pr-writing-review=copilot 指定した reviewer で本文を確認する
pr-writing-review=off 本文 reviewer を明示的に使わない

まず何が起きるか

  1. 呼び出し元の明示指定 > default branch の順で base を決め、base…HEAD の最終差分、commit 履歴、PR template、linked Issue を確認する。
  2. diff だけでは分からない背景、理由、期待状態、review focus を抽出する。
  3. 実施済みの検証と E2E、未実施項目の理由を本文へまとめる。
  4. 本文の読みやすさ、証跡、Issue との重複、内部運用語の混入を検査する。
  5. 必要な場合だけ本文 reviewer の指摘を反映し、再検査する。
  6. review-orchestrator pr-publication push で branch を push し、review-orchestrator pr-publication create で PR を作成する。
  7. base、head、draft 状態、assignee、本文が意図どおりかを GitHub で確認して URL を返す。

通常 PR と Draft PR のどちらにも self-assignee を設定する。 作成時点で未確認の CI、review、E2E を成功済みとは書かない。

Stacked PR を作る場合

stack=<PR number|PR URL|auto> または stack-base=<branch> を指定した場合だけ、stacked PR の作成手順を使う。stack=true は stack=auto として扱う。両方を指定した場合は停止する。

stack は保存済みの解決結果を PR 作成直前に再検査し、親 PR、base branch、base OID が変わっていれば PR を作成しない。auto は linked source Issue を一意に特定できる場合だけ使う。

再検査では legacy parent_pr_not_top artifact も読み込める。logical_dependency_pr と effective_tail_candidate が観測されても blocked result は維持し、後続 coordinator の判断なしに publication base へ採用しない。

後続 coordinator は pr-publication stack-register、stack-ready、stack-heartbeat、stack-status を使い、worktree 間で共有する publication intent と凍結順を repo-scoped state に記録する。stack-prepare、stack-renew、stack-complete、stack-abort は publication lease と restack 後の tail を管理する。明示 auto stack と serial-stack は required で実行し、report-only mode は rollback 後の観測に限定する。

親 Issue の表が更新された場合は、未公開 intent の row と相対順を再確認する。相対順が同じなら snapshot と Phase を更新し、並び替えまたは row 消失なら publication_order_stale で lease と branch の変更前に停止する。

復旧するときは、親 Issue の表で元の相対順と欠けた row を復元してから、resolver と intent 登録をやり直す。順序変更を維持する場合は、既存 intent を resume または abort の手順で解決してから、新しい順序で登録する。

standalone root は検証済み original base で intent を登録します。外側 workflow から呼ばれた nested create-pr は read-only status で current intent と revision を再取得し、restack 後の HEAD と refreshed base を使います。coordinator の base を明示 PR selector として再解決しません。

auto coordinator 経路は source Issue と required の closing Issue gate を PR 作成へ渡します。不一致は mutation 前に止めます。

false stop、unsafe pass、duplicate publication、順序違反、closing Issue の誤停止または見逃しがあれば、両 gate を report-only に rollback します。残存 intent は required registry へ持ち越しません。

PR 作成後は stack adjacency と closing reference を確認して publication intent を完了します。

親 PR の解決、branch と差分の検査、PR の連結、merge の詳細は、source repo の claude/skills/create-pr/references/stacked-pr.md を参照する。

PR 本文に残す情報

本文は base…HEAD の最終状態を説明し、レビュー対応や試行錯誤の時系列は残さない。 コードや diff を読めば分かる変更列挙を減らし、次の判断材料を残す。

  • 変更前に何が困っていたか
  • この PR でどの状態になったか
  • reviewer が確認すべき判断、制約、残リスク
  • 実行した検証、E2E、CI の結果と確認できる証跡
  • 実施していない確認と、その理由

linked Issue がある場合も、Issue を開かずに背景、理由、期待状態、review focus が分かる本文にする。 Issue 全文を言い換えず、narrative の先頭は課題と実現した状態を合計2〜4文、300字以内でまとめる。

関連 Issue は、PR が完了させる対象だけを Closes #N / Fixes #N で示す。 Issue の Design doc section に実 URL がある場合は、その行の直下へ 実装イメージ: [design doc](URL) 形式の link を置く。 省略理由だけの場合は追加しない。

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

検証と証跡

workflow から呼ばれた場合は、変更種別に応じて必要な証跡をそろえる。 単体で本文だけを作る場合は、新しい test を勝手に実行せず、取得済みの事実を使う。

  • 実行済みの 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 は変更しない。

公開結果

PR 作成後は、GitHub 上の URL、通常 PR / Draft PR の別、assignee、確認済みの検証状態を報告する。 PR 本文には実行 runtime を示す AI attribution フッターを自動付与し、正規の 1 block だけを残す。

同じ turn で CI、review、E2E の結果が新たに確定した場合は、完了報告前に update-pr で本文を最新化する。 作成時点の暫定表現を残さない。

停止後の対応

  • 対象 branch、base、linked Issue、PR 作成 scope を一意に決められない場合は、作成前に確認する。
  • 本文検査で未解消の finding が残る場合は、本文を直して再検査する。修正 round の上限に達した場合は PR を作らず報告する。
  • 指定した本文 reviewer を開始できない場合は、別 reviewer へ黙って変更しない。利用可能な transport と許可を確認する。
  • 必要な検証や E2E 証跡が欠ける、または current HEAD と一致しない場合は、再実行か理由付き未実施へ戻す。
  • push、PR 作成、self-assignee、作成後確認のいずれかが失敗した場合は、確認できた公開状態を読み直して同じ作成 intent を再開する。

失敗時に gh pr create を直接呼んで guard を回避しない。 PR URL は作成後の確認が通ってから報告する。

このページは生成物です。原本は元リポジトリ側にあります。