update-pr-description

現在のブランチに紐づく PR の説明を、ベースブランチに対する差分観点で書き直して更新してください。PR 本文に加えて、自分が投稿した補足情報用のコメントも更新対象です。

本文の見せ方は、mattpocock-skills の pr から2つを取り込む。変更の前と後を並べて見せること（画面・出力・テストの結果）と、取り消せる変更か・影響がどこまで及ぶかを書くこと。節の構成は、pr の英語のテンプレートではなく、リポジトリの PR テンプレートと下記の方針に従う。

進め方

1. PR の特定

   • git branch --show-current で現在のブランチを確認
   • gh pr view --json number,title,body,baseRefName で対応する PR を特定（該当 PR が無ければユーザーに確認）
   • 作成者を確かめる（ gh pr view <PR> --json author -q '.author.login' ）。ユーザー本人でなければ中断して報告する（ no_operating_on_others_prs.md ）
   • baseRefName を以降の差分計算のベースに使う
   • 本文に自分が書いていない内容が入っていないか見る
     • 投稿者では判定できない。 ユーザー名義で投稿するので、こちらの編集も相手の編集も同じ login になる
     • 添付の参照を数える。 ![ user-attachments <video githubusercontent を現在の本文から拾い、新しい本文にも同じものがあるかを見る
     • 画像・動画・スクリーンショットが最も消えやすい。 本文をテキストとして組み立てるので、添付は持ち回らない
     • 消したことに気づけるのは投稿者だけで、こちらからは見えない。取得しただけでは足りず、添付という観点で数える
     • 消してしまったら userContentEdits から復元できる（ keep_records_current.md ）。ただし指摘されるまで気づけない

   作業ツリーが別のリポジトリなら git を打たずに同じ手順を回す。 worktree へ隔離されたセッションでは、他のリポジトリを対象にした git の実行がハーネスに拒否される。そのままでは Step 1 と2が成立しない。

   手順	代わりに使うもの
   git branch --show-current	PR 番号を引数で受け取る
   git diff <base>...HEAD	gh pr diff <PR> --repo <owner/repo>
   git show <ref>:<path>	gh api "repos/<owner/repo>/contents/<path>?ref=<branch>" （ -H "Accept: application/vnd.github.raw" ）
   /triage-why-comments （手順2）	同じ置き換えで回せる。git を使うのは差分の取得だけ

   この置き換えで回すときも、Step 6 の点検は飛ばさない。 スキルを起動できないので手順を記憶で回すことになりこの段が最初に抜ける。実際に2本の PR を投稿してから点検へ通し、指摘が4件出て同じ PR へ2回投稿することになった。

2. 差分の把握（並列実行可）

   • git diff <base>...HEAD --stat でファイル単位の規模感

   • git diff <base>...HEAD で全変更内容（大きい場合は要点だけ抜き出す）

   • テンプレートがあるなら、必ずその構成で書く。 節の追加・削除・並べ替えはしない。本ファイルと references/ の規定（4点の軸・何の話かを先に置く等）は、テンプレの各節の中身で実現する

   • テンプレートは base のブランチから探して読む（ git show origin/<base>:<テンプレートのパス> ）。置ける場所は3か所あり、.github/ だけ見ると見落とす

     git ls-tree -r --name-only origin/<base> | grep -iE '^(\.github/|docs/)?pull_request_template(\.md|/)'
     

     置き場	例
     リポジトリ直下・docs/・.github/	.github/pull_request_template.md （大文字の PULL_REQUEST_TEMPLATE.md もある）
     3か所それぞれの中の PULL_REQUEST_TEMPLATE/	複数のテンプレート。どれを使うかは PR の種類に合うものを選び、迷ったらユーザーへ尋ねる

     リポジトリに無ければ、owner の .github リポジトリの既定を見る（ gh api repos/<owner>/.github/contents/ で上と同じ名前を探す）。そこにも無いときだけ、シンプルな「Summary」「Test plan」構成にフォールバックする

     • 作業ツリーのものを Read しない。 別のブランチのものを読むことになる。base が develop のとき、main にしか入っていない節を読んでしまう。リリースの流れが一方向だと、上流の変更が下流へ降りていないことがある
     • ファイル名の大文字小文字はリポジトリで違う。 macOS のファイルシステムは区別しないので Read では気づけない。git ls-tree origin/<base> .github/ --name-only で実体を見る
     • 既存本文から構成を推測しない。テンプレが更新されていることがある

   • /triage-why-comments を呼び、コードコメントとインラインの [fyi] を整える（書く・削る・直す・振り分ける）

     • 本文を組み立てる前に呼ぶ。 コードコメントを直すと差分が動くので、後に回すと Step 5 の照合をやり直すことになる
     • コードを直したらコミット・push してから次へ進み、以降の差分の把握は push 後の head で行う
     • --skip-triage を渡されたら飛ばす。 /finalize-prs が手順2で済ませてから渡す

3. 本文・補足コメントの組み立て方針

   このファイルと references/ の3本（ body.md testing.md multi-pr.md ）が正本。 /create-pr からも参照される。 あちらへ写さない。 写すと片方だけ古くなる（実際に58行ずれた）。 節単位で読まない。 「この節が正本」と書いていた時期は、## 進め方 の Step 5（本文と差分の照合）と ## やってはいけないこと が宣言の外にあり、27行が写された。 作成のときにだけ要るもの（テンプレの埋め方・reviewer・base）は /create-pr 側に置く。 固有名を含む手順も同じ（課題管理ツールの URL・プレフィックス・MCP の呼び方）。公開側には書けないので、判定だけ本ファイルが持つ。

   本文を書く・直す前に references/body.md を Read する。 動作確認の節を書くなら references/testing.md、1つの課題を複数の PR に分けたときと Backlog 節は references/multi-pr.md も読む。下の各項目は要点だけで、判定の中身は参照ファイルにある。

   この方針は PR 本文と別コメントの両方に等しく適用する。 別コメントは「細部を置く場所」であって「基準を緩める場所」ではない。量・流れ・表と図・過程を書かないことは同じく守る。

   • PR 内のコミット履歴・レビュー対応の経緯は書かない。merge された時点のスナップショットとしての変更観点に徹する
   • 読み手が拾う4点を軸にする。 何を変えたか・なぜ変えたか・何がリスクか・どう検証したか。長くなるのは構わず、4点を拾うまでの手間で判定する（詳細は references/body.md の「読み手が拾う4点を軸にする」）
   • 概要は3つの小見出しで書く。 冒頭に何の話かと何をするかを1〜2行で置き、「なぜこの変更が要るか」「何が変わるか」「この PR の位置付け」を毎回小見出しにして続ける（詳細は references/body.md の「概要は3つの小見出しで書く」）
   • 届く範囲が差分から読み取れないときは、段を分けて書く（詳細は references/body.md の「届く範囲が差分から読み取れないときは、段を分けて書く」）
   • 既存の構成を変えるなら、いまの構造が歴史的経緯によるものだと示す（詳細は references/body.md の「既存の構成を変えるなら、いまの構造が歴史的経緯によるものだと示す」）
   • 修正前と修正後を、観測できる挙動で並べる（詳細は references/body.md の「修正前と修正後を、観測できる挙動で並べる」）
   • 動作確認をしていない旨を書かない（詳細は references/testing.md の「動作確認をしていない旨を書かない」）
   • 過不足なく書く（詳細は /format-post の references/writing.md の「過不足なく書く」）
   • 概要から詳細へ流す（詳細は /format-post の references/writing.md の「概要から詳細へ流す」）
   • 読み手はその機能を知らないエンジニア（詳細は /format-post の references/writing.md の「読み手はその機能を知らないエンジニア」）
   • Alert / <details> / 脚注も使う（土台は /format-post ）。Alert は IMPORTANT と WARNING だけを、本文に1〜2個（生成者表示の Note は数えない）。先に「読み飛ばすと事故になるか」で選び、超えたら畳み方を見直す
     • <details> は使えるところでは使う。 畳むのは根拠の実体だけで、判断に使うものは見せたまま。畳んだら結論を外に1行置く（判定は /format-post の「何を畳み、何を見せたままにするか」）
   • 表と Mermaid 図で畳む（詳細は /format-post の references/writing.md の「表と Mermaid 図で畳む」）
   • 個人環境にしか無いものを前提に書かない。 グローバルスキル（ ~/.claude/skills/ ）やグローバルルール（ ~/.claude/rules/ ）は自分の環境にしか存在せず、他のレビュアーには無い。「 /commit-push で代替できる」のような説明は成立しないので、リポジトリにコミットされているもの（プロジェクトスキル・.claude/rules・docs/ ）だけを根拠にする
     • 同じ理由で、個人環境のルールを根拠にプロジェクトの資産を消さない。リポジトリにあるファイルはチーム全員のもの
   • 外部ドキュメントで足りることは書かない。Design Doc / PBI / Figma / 他 PR の背景・仕様・経緯は1〜2行に要約してリンクを貼り、PR 本文で再構成しない。例外は差分を読むのに必要な前提で、その場合も必要な部分だけ引用する
     • DD で決まっている判断に独自の根拠を足さない。「DD の方針どおり」で足りる。根拠を書くのはDD から外れた点とDD 執筆後に決めた点だけ
   • 他リポジトリの PR / issue は owner/repo#123（同一リポジトリなら #123 ）。GitHub が自動でリンクにし、タイトルと open/closed も表示される。生 URL より短く、リンクが切れない。owner を省略しない（ repo#123 は同一リポジトリの番号と解釈されてリンクにならない）。例外はコメントへのアンカー付き参照（ #123#issuecomment-... ）で、これは Markdown link にする
   • 1つの課題を複数の PR に分けたなら、他の PR と書き方を揃える（詳細は references/multi-pr.md の「1つの課題を複数の PR に分けたなら、他の PR と書き方を揃える」）
   • 本文は軸、細部は別コメント（詳細は references/body.md の「本文は軸、細部は別コメント」）
   • Backlog 節への対応（詳細は references/multi-pr.md の「Backlog 節への対応」）
   • 本文の末尾に生成者表示を置く（ github_note_generated_by_claude.md ）。付けるかどうかの判定と、文言と主語の使い分けはあちらが持つので、ここには写さない（自分たちが管理していないリポジトリでは付けない）

4. タイトルの妥当性チェック

   • 現在の PR タイトルがベースブランチに対する差分の意図を正確に表現しているかを判断

   • スコープ拡張・方向転換・修正対象の変化などで乖離している場合はタイトルも更新対象に含める

   • 70文字以内、要点が動詞で始まる形（例: feat: ..., refactor: ... ）を維持

   • チケット番号を付けるかは ~/.claude/references/karma_commit_style.md の「PR に番号を付けるか」に従う。ここに写さない（判定を2箇所に持つと片方だけ古くなる）

     Backlog 節と突き合わせる。Backlog が「なし」なのにタイトルが番号を名乗る形が最も出やすく、課題側の「Pull Request」属性から辿った人が期待と違うものを見る その課題の調査中に見つけた別件なら、番号を付けたうえで本文へ「この課題を閉じる PR ではありません」を1行残す

   • 乖離していなくても、もっと伝わるタイトルがあれば直す。 判定は「タイトルだけを読んだ人が、マージすると何が変わるかを言えるか」。対象の呼び名が画面や仕様の語と合っているか、本文の「何が変わるか」と食い違っていないかも見る

   • 迷ったら直す。タイトルは PR の一覧と課題の「Pull Request」属性に並ぶ索引で、直しても失うものは無い

5. 本文と差分の照合: 更新する前に、書いた内容が実際の差分と食い違っていないかを機械的に確認する。書き直しは既存本文の古い記述を持ち越しやすいので、既存を流用した箇所ほど疑う。

   3周で見る（ recheck_after_every_revision.md ）。同じ読み方を3回しても同じ箇所しか見ないので、周ごとに観点を変える。下記の項目はその3周に振り分けて使う。

   • 照合は作業ツリーではなく ref を指定して行う。git show <ref>:<path> と git diff <base>...<ref> で数える
     • 作業ツリーは自分の操作だけで決まらない。 同じディレクトリを別のセッションが使っていると、checkout した記憶どおりの状態とは限らない
     • スタックした PR では特に起きる。 段ごとに別のブランチなので、どれを見ているかで結果が変わる
     • 0件が返っても手が止まらない。 「まだ実装していない」と読めるので、空振りだと気づけない
     • 作業ツリーで数えるなら、先に git branch --show-current で対象と一致していることを見る
   • 数値: 変更ファイル数・テスト件数・使用箇所数など。git diff --name-only | wc -l や実行結果と突き合わせる。「N 箇所」と書いたら必ず数える
   • 識別子: 型名・関数名・定数名・ファイルパス・コミットハッシュ・マイグレーション名が実在するか。grep / git log で確認する
   • 主張: 「〜には影響しない」「〜は変わらない」と書いたなら、その根拠をコードで裏取りする。影響範囲の断定は誤ると事故になる
   • 決着済みの記述: 「未確定」「判断待ち」としていた項目が、その後決まっていないか
   • 他リポジトリへの言及: 依存する PR 番号・ファイル名が正しいか。参照先が変わっていないか。本文中の #数字 をすべて拾い、他リポジトリのものに owner が付いているか1箇所ずつ確かめる（前半だけ正しく後半で崩れているのを見逃しやすい）。囲んだ側も別に数える（ `grep -oE '`[A-Za-z0-9_./-]*#[0-9]+`'` ）。owner の検査では当たらない
   • 因果の鎖: 前提を知らない人が上から読んで、各主張の理由が本文の中だけで辿れるか。1文ずつ「なぜそう言えるか」を問い、答えが本文に無ければ暗黙の前提が残っている
   • 指すものが決まらない語・読点・1文の長さ・否定: /format-post の references/writing.md の「投稿前に拾うもの」で1行ずつ拾う
   • 食い違いが見つかったら本文を実態に合わせる（差分の方を本文に合わせない）

6. 更新

   • 投稿前に /japanese-tech-writing を当ててから /yomiyasu:yomiyasu を通す（ no_ai_style_writing.md の「文章の点検を通す場面と順序」）。Step 5の照合を終えた本文に当て、書き直しは取捨選択する。このリポジトリ・プロジェクトの規約（行末の句点を落とす等）と矛盾する書き直しは採らない。新規に書く補足コメント（手順7）とインラインの [fyi] （ references/body.md ）も同じ扱い
   • 投稿の直前にもう一度本文を取得し、Step 1 から増えていないか見る。組み立てている間に追記されることがある
     • 比べる前に改行コードと末尾の空行を揃える。 取得した本文は CRLF で返るので、ローカルで組み立てた LF のファイルと素で比べると毎回「差あり」になる。警告として働かなくなり、本物の差分が混ざっても手が止まらない
     • 添付の数はここで数え直す。 Step 1 で0件でも、組み立てている間にユーザーが貼ることがある。実際に、貼られた動画2本を全文置換で消した
     • 差分が出たら投稿しない。 何が増えたのかを確かめ、新しい本文へ取り込んでから出す
   • 本文はファイルに書き出し、--body-file で渡す
     • そのファイルを作るのと同じ呼び出しに入れない。 書式を検査するフックは PreToolUse で走るため、その時点でファイルが無いと「Note が無い」「添付が消えている」と誤検知して弾く。作成と投稿を別の呼び出しに分ける（ decide_or_ask.md ）
     • これは全文置換で、渡さなかった行は消える。 自分が書いていない内容も組み立てへ含める
   • タイトルも更新する場合は --title "..." も併用（シェル展開されないクオートに注意）

7. 補足情報用コメントの点検と更新

   PR 本文に入りきらない情報を別コメントに切り出している場合、本文と同じ鮮度で保つ。本文だけ直してコメントが古いまま残ると、読み手はどちらが正しいか判断できない。

   • 対象の抽出: gh api repos/OWNER/REPO/issues/<PR>/comments --paginate で自分が投稿したコメントを取得し、情報を提供しているものに絞る
     • 対象: BE 向けの契約・データモデル、調査結果、確認手順、設計判断の記録など、後から参照される情報
     • 対象外: /ai-review 等のコマンドコメント（ github_writing.md ）、単なるリンク共有、レビュー返信（ pulls/<PR>/comments 側）
     • [fyi] が付いていても中身が情報提供なら対象（切り出した補足コメントには [fyi] を付ける規約のため、接頭辞では除外しない）
     • 見出し (##) を持つ長文かどうかで機械的に絞れる。前後の空白でコマンドを取りこぼすことがあるので、本文を trim してから判定する
     • 除外したものを「補足コメント」としてユーザーに報告しない。 投稿者はユーザー名義でも中身はコマンドで、点検しても更新すべき事実が無い
   • 点検の観点: 最新差分と突き合わせ、事実がズレていないかを機械的に確認する
     • コメントが挙げている型・フィールド・定数が、実装に存在するか
     • 件数・行数・テスト数などの数値が実測と合うか
     • 「未確定」「判断待ち」としていた項目が、その後決着していないか
     • 手順3の「削る型」に当てはまる記述が無いか。断り書き・検討の過程・本文との重複は、点検のたびに落とす。コメントは追記で伸びやすい
   • 更新: ズレがあれば gh api -X PATCH repos/OWNER/REPO/issues/comments/<comment_id> -f body="$(cat <<'EOF' ... EOF)" で更新する
     • 末尾の Note ブロックを消さない（ github_note_generated_by_claude.md 参照）。本文を差し替えるときは Note を含めて組み立てる
   • 本文からのリンクを確認する。切り出したコメントが本文から辿れる状態かを見る。無ければ本文に足す
     • 新たに切り出して投稿した場合も同じ。gh pr comment が返す URL を本文へ差し込む。投稿時は冒頭に [fyi] を単独行で置き（次の行から本文）、末尾に Note ブロックを付ける
     • 置き場所は「その情報を探す人が見る節」。契約なら実装内容、調査ログなら補足
     • リンクが無いと本文だけ読んだ人がコメントの存在に気づけない
   • 本文とコメントで同じ情報を二重に持たない。詳細はコメント側に置き、本文からは参照リンクを貼る形にする
   • そのうえで、同じ対象を述べた数値と有無が食い違っていないか照合する。二重に持たないと本文がコメントの要約になるので、そこで例外と条件が落ちる
     • 落ちる向きは一定。 コメント側の例外が本文で消える（ keep_records_current.md ）。**本文が「〜は無い」、コメントが「N 件ある」**の形が出やすい
     • 数値を機械的に抜くだけでは足りない。 両方から拾って差集合を取っても、細部の数値はコメントにしか無いのが正常なので食い違いが埋もれる。実測でこの形（本文「1件もありません」/ コメント「263件」）は検出できなかった
     • 本文がコメントを要約している段落を先に特定し、その段落だけを原文と並べて読む。 対象が絞れているので、目で読んでも見つかる

8. 完了報告: 更新後の PR URL、書き換えた本文の要約、タイトル変更があればその旨も返す。補足コメントを更新した場合はその URL と更新内容も併記する。

   • Step 5 の3周を、周ごとに何を見たかで報告する。 項目が揃っていても実行しなければ意味が無いので、通したことを可視化する

     1周目（事実）: 数値5件・識別子8件を出どころへ戻して照合
     2周目（筋）  : 各主張の根拠が本文の中だけで辿れるか1文ずつ
     3周目（形）  : 表6個・Alert 1個・`**` の奇数行0件
     

   • 周を飛ばしたなら、飛ばしたと書く。 「3周した」と書いて実際は1周なら、次に同じ抜け方をする

出力の目安

• 本文/タイトル/コメントとも変更なしで済んだ場合: 「差分と本文・コメントが既に整合。更新なし」で2〜3行報告
• 本文更新した場合: 更新後 URL + 主な変更点（追加した節・修正した節・タイトル変更の有無）を簡潔に
• 補足コメントも更新した場合: コメント URL と、どの記述が実態とズレていたかを1〜2行で添える

やってはいけないこと

• コミット履歴・レビュー対応の経緯を本文に書くこと（差分スナップショットに徹する）
• 同一内容の本文を再送すること（差分と本文が既に整合しているなら更新しない）
• 差分と乖離していないことだけを理由に、タイトルの見直しを飛ばすこと。もっと伝わる形があるなら直す
• 複数の対応を含む PR で症状を散文のまま並べること。何件あるのかが読み取れない
• テンプレの構成から外れること。節の追加・削除・並べ替えのいずれもしない。見つけたテンプレート（手順2）が正で、変えるのは各節の中身だけ
• Design Doc / PBI に書かれている仕様をゼロベースで説明し直すこと。要約1〜2行 + リンクで足りる
• 別コメントへ切り出したのに本文からリンクを貼らないこと（読み手がコメントの存在に気づけない）
• 本文だけ更新して補足コメントを古いまま放置すること（どちらが正しいか読み手が判断できなくなる）
• 補足コメントを更新する際に末尾の Note ブロックを落とすこと（ github_note_generated_by_claude.md ）
• 本文に書いた数値・識別子・影響範囲の主張を、差分と照合せずに更新すること（Step 5）。既存本文を流用した箇所ほど古い記述が残りやすい
• 届く範囲を、変更ファイルの一部だけ見て断定すること。paths-ignore は全件が一致したときだけ効くので、1件見落とすと結論が逆になる
• 自分が書いていない内容を、全文置換で消すこと。画像・動画は特に消えやすく、消したことに気づけるのは投稿者だけ
• 他人が投稿したコメントを編集すること（対象は自分が投稿したものだけ）
• 1つの課題を分けた他の PR と、書き方を突き合わせずに書くこと。レビュアーは並べて読むので、同じことが別の言い方だと差の有無を毎回確かめることになる（Step 3）
• 相手セッションが担当する PR の文言を、記憶で揃えること。実物を送ってもらってから決める