/da-pr-describe — 差分より先に PR を読めるようにする

ユーザーが /da-pr-describe と打った時だけ動く。 GitHub に書き込むので、タイミングはユーザーが選ぶ。コードが仕上がって見えることから推測しない。このスキルを名前で呼び出すものは無い。

レビュアーが差分を開かずに 何が変わるか と なぜその形にしたか を掴めるタイトルと説明を作る。網羅より理解されることを優先する。

このスキルはリポジトリのファイルを変更しない。 編集するのは GitHub 上の PR で、下書きの本文はリポジトリ外の一時ファイルに書く。

実行条件

ワークフロー上の位置

読むファイル

常に読む

条件つきで読む

手順

Step 1. PR を特定し、正しい PR か確かめる

gh pr view --json number,title,baseRefName,headRefName,url

gh は作業ディレクトリのリポジトリに対して動く。 別のディレクトリから gh pr edit <number> を打つと、そちらのリポジトリの同じ番号の、無関係な PR を編集する。編集の前に、変更するリポジトリ・番号・タイトル・URL を示してユーザーの確認を取る。番号だけを信用しない。

Step 2. 変更を集める

BASE="$(gh pr view --json baseRefName -q .baseRefName)"
git diff "$BASE"...HEAD
git log --oneline "$BASE"..HEAD

Step 3. 他人にとって実際に変わったことを抜き出す

差分から、利用者・運用者・呼び出し元にとって何が変わるかを抜き出す。選び方は reference の規則に従う。

残した変更ごとに それが解く問題（障害、要望、目標）を抜き出す。無いと、書かれていない問題への解決策に読める。

次に、明らかな代案を却下したかを問う。 却下したなら、代案とそれを退けた根拠（遅いフラグ、本物のエラーを隠す狭い除外、CI が見なかったデプロイ時の失敗）を名指しする。無いとレビュアーは「なぜこの形？」を聞くために差分を開く。これは節である 検討した代案 に入れ、数字やリンクを持てるようにする。本当の代案が無ければ その節を消す。問題を言い換えて埋めない。

変更ごとに次も決める。

• 領域: 読み手の語彙での領域（画面、API、CSV 出力、運用手順）。クラス・関数・フラグにしない。
• 変更前 / 変更後 の組: 現在の値や挙動と、それが何になるか。どちらも短く。純粋な追加なら —。変更前 / 変更後 の組で書けない変更は内部の入れ替えの兆候であり、表に入れない

この 3 つが表の列で、3 つとも短い値。 問題と却下した代案は文章であって 4 列目ではない。セルはインラインの書式しか持てず、文の列は行幅を決めて、一覧性を担う 3 列を押しつぶす。チケット・issue・設計ドキュメント・ベンチマークへのリンクもここで集める。置き場は 概要。

別に 手動確認 の候補を集める。自動テストで覆えず、マージ前に手か実環境で確かめるもの。実際の外部 API の挙動、実データ、実テナントでの end-to-end、エージェントに実行が許されていない typecheck、環境固有の設定や権限。

Step 4. 全体像 — 描けるものがある時だけの節

まず、変更に形があるかを問う。 変わったフロー、順序、触れる層、状態遷移。フラグの値が変わるだけなら形は無く、表がすべてを言っている。埋めるために描かず、節ごと消す。 URL を作り上げない。

見出し（## 全体像）で、概要 の上に置く。検討した代案 と同じく、描くものがあればあり、無ければ無い。 任意の節はこの 2 つだけで、同じ扱いにする。

形がある時は、環境が支える経路を取る。

共有はこのスキルの手順であり、注意書きではない。 Artifact は既定で非公開で、ツールに共有の操作は無い。チームに見せるのは人間が Artifact の画面で行う。未共有のリンクは作者には開けてレビュアー全員には 404 になり、誰も確かめない方向に黙って失敗する。

公開 → 止まって URL を示し、ユーザーに共有を頼む → その後で本文に入れる。 共有したくないなら Mermaid のフェンスを使う。レビュアーが開けないリンクは図が無いより悪い。 存在する中身のように読めるから。

どちらの場合も 変わること の表を言い直さない。 本文にすでに一覧があり、それを繰り返すページや図は開いて閉じるものが 1 つ増えるだけ。

Step 5. タイトルと本文を組み立てる

言語はリポジトリに合わせ、決めつけない。 この出力の読み手は自分ではないので、単に日本語とはしない。

gh pr list --state merged --limit 5 --json title,body

これか最近のコミットの件名を読み、使われている言語で書く。テンプレの見出しは日本語が既定で、reference に英語の対応がある。 表の構造と 3 列は言語によらず同じ。

どの言語を選び、何を根拠にしたかを書く。マージ済み PR の言語が混在しているか、手がかりが無ければ 尋ねる。誤りは PR の全員に見える。パス、識別子、コマンド、コード片はどちらの言語でも文中でそのまま残す。

${CLAUDE_SKILL_DIR}/reference/pr-template.md に従う。Step 4 で URL か Mermaid ブロックができたら、本文の最初の節 ## 全体像 に置く。どちらも無ければその見出しは無い。URL は、Artifact が共有済みだとユーザーが確認してから入れる。 Markdown の表と Mermaid のフェンスは本文に書き、生の HTML は書かない。 GitHub が多くを取り除き、残ったものも崩れる。

Step 6. 見せてから更新する

最終のタイトルと本文をユーザーに見せる。承認されたら次を実行する。

gh pr edit --title "..." --body-file "$TMPFILE"

$TMPFILE は一時ディレクトリの下に書き、リポジトリの中には書かない。

完了条件

• 説明だけで何が変わるかレビュアーに分かる
• 概要 が問題を運んでいる（利点でも変更の言い直しでもない）。チケット・issue・設計ドキュメント・ベンチマークの数字は落とさずそこにリンクした
• 検討した代案 は実際に却下した代案がある時だけあり、退けた根拠を持つ。無ければ埋めずに消した
• 領域 のセルがクラス・関数・フラグを名指ししていない
• 表のセルに文が無い。 どのセルも値か短い句
• 表の行はすべて 変更前 / 変更後 の組で書けている。組にできない行は内部の入れ替えとして落とした
• ## 全体像 に図があるか、変更に形が無いので節ごと無い。中身の無い見出しも、埋めるための図も無い
• Artifact のリンクなら、共有済みだとユーザーが確認した。リンクが自分で開けることからは推測できない
• タイトルは単独で立つ命令形の 1 文で、リポジトリの言語で書いた
• 言語はマージ済み PR から選び、何を選んだかを書いた
• 内部だけの入れ替えが本文に入っていない
• 手動確認が要るものはすべて、未チェックのまま理由つきで挙げた
• リポジトリをまたぐ参照は完全な URL か owner/repo#number で、裸の #number ではない

リポジトリをまたぐ危険

どちらも実際に起き、どちらも大きな音を立てずに失敗する。

#number は PR 自身のリポジトリの中で解決される。 バックエンドの PR 本文の #80 は、意図したフロントエンドの PR ではなくバックエンドの #80 を指す。リポジトリをまたぐなら常に完全な URL（https://github.com/owner/repo/pull/80）か owner/repo#80 を使う。バックエンドとフロントエンドにまたがる PR 群では、すべての相互リンクと共有成果物の注記をその形にする。

gh は作業ディレクトリのリポジトリに対して動く。 複数リポジトリの PR を扱う時は、コマンドごとに対象リポジトリへ cd し、gh pr view <number> --json title で意図した PR か確かめる。