summarize-prs

複数の PR で何が直り、どう直したかを、1本の報告文へ畳みます。

既定の読み手はその機能を知らない非エンジニア（品質保証の担当・企画・課題の報告者）です。軸は2つあり、語彙を開くことと、文章として書くことはそれぞれ別の働きをします。

軸	中身
語彙	内部の呼び名を開き、画面に出ているものの名前で書く
形式	段落で書く。表や図を主役にしない

PR 本文の要約ではありません。 PR 本文はレビュアー向けで、読み手が差分を見る前提で書かれています。報告文の読み手は差分を見ないので、書く順も語彙も変わります。

対象

使う	使わない
完了報告・確認依頼の文面を作る	PR 本文を書く（ `/update-pr-description` ）
複数の PR をまとめて1件の課題として報告する	実装の中身を噛み砕く（ `/explain-code` ）
開発の外にいる人へ渡す	担当 PR の状況を自分で見渡す（ `/list-prs` ）

読み手で変わるのは語彙の開き方だけ

形式は変わりません。 どの読み手でも文章として書き、変わるのはどこまで開くかです。

読み手	開き方
非エンジニア（既定）	内部の呼び名を全部開く。原因は「どういう作りだったか」まで
別領域のエンジニア	内部の呼び名は開くが、一般的な技術用語はそのまま
同じ領域のエンジニア	このスキルは要らない。PR 本文で足りる

--for が渡されていればそれを使う。報告先が読み取れず、開き方が変わりそうなときだけ AskUserQuestion で尋ねる。

読み手が社内の人なら、社内で通っている呼び名を括弧で補ってよい。 画面の名前だけではどれか決まらないことがあり、併記があると照合できます（「〜のカード（社内の呼び名）」）。開発の中だけで使う語は補っても意味を持たないので、対象は画面や機能を指す呼び名だけです。

貼る先で変わるのは記法だけ

文章の中身は変わりません。 変わるのは記号と宛先の置き方です。

貼る先	変わること
チャット	宛先をメンションで冒頭に置く。絵文字が使える。課題へのリンクは冒頭に1つだけ（末尾へも置くと重複する）
課題管理ツール	そのツールの記法に合わせる。課題の中なのでその課題の URL は要らない
メール・不明	素の文章と `-` の箇条書きだけで通じる形にする

貼る先が分からなければ尋ねる。 記法を外すと、記号がそのまま文字として出ます。

既に投稿されたものを参考にするなら、描画された姿で見る。 テキストだけでは記号が描画されたのか文字として出たのか区別が付きません。

宛先の状態が分かっているなら添える。 休みや不在が分かっていればメンションの後ろに置くと、読む側が返信を急がずに済みます。

進め方

1. 実物で裏を取る

引数の PR 番号（または URL）を対象にする。省略時は現在のブランチの PR 1本（ gh pr view --json number ）。

PR 本文だけを読んで畳まない。本文が実態と食い違っていることがあります。

gh pr view <PR> --json title,state,body で本文と状態
gh pr diff <PR> で実際の差分
実装の確認は Read / Grep / Glob で行う
「直した」と書いてあるものが本当に差分にあるかを照合する

触っていない画面を報告に入れない。 逆に本文に書き忘れた修正が差分にあることもあるので、差分の側からも拾う。

2. 症状・原因・対応へ仕分ける

3つに分けてから畳む。 混ざったまま書くと、読み手が原因と対応を区別できません。

仕分け	何を書くか
症状	その人が画面で見たこと（「星が点かない」「カードが消えない」）
原因	どういう作りだったからそうなったか。内部の呼び名を使わずに
対応	どう変えたか。読み手が確認できる形で

症状だけでは報告になりません。 原因が分かると、読み手は似た症状が他にもないかを自分で疑えます。

3. PR の境目を消して1本へ畳む

PR 番号で節を分けない。 読み手にとって PR の分かれ目は意味を持たず、同じ症状が2本に散っていると2回読むことになります。

畳む軸	例
画面・機能	「一覧のほか、同じ症状が〜にも出ていたため」
症状の種類	「表示が変わらない問題」と「操作の対象が違っていた問題」
PR 番号	使わない

課題番号は使ってよい。 読み手が追う単位はそちらです。

4. 文章として書く

段落で書く。 症状を表にすると網羅はできますが、読み手には全体像が見えません。知りたいのは「何が直って、どこを見ればよいか」で、症状の一覧はその手段です。

貼る先の記法は不明なものとして扱う。 課題管理ツール・チャット・メールのどれになるか分からないので、見出しと太字に依存しない。素の文章と - の箇条書きだけで通じる形にする。

記法が分かっている場面で表を使う判断は /format-post と concise_first_then_detail.md が持ちます。 ここで上乗せするのは、症状ごとの Before / After を並べた表は3つ目から量が中身を上回るという1点だけです。

データが失われる系の症状は、独立した段落に出す。 表示の不具合と並べると埋もれます。「消えるはずのないものが消えていた」「別の対象へ操作が飛んでいた」は、読み手が最初に知るべきことです。

5. 確認範囲を渡す

画面の一覧だけでは足りない。 症状が特定の操作でしか出ないなら、その操作も書く。

対象の画面（読み手が使っている呼び方で）
操作の軸（1件ずつと複数選択、保存と解除、初回と2回目）

呼び方を文中と確認範囲で揃える。 同じ画面を本文で「〜の中身を見る画面」、一覧で「〜詳細」と書くと、読み手は別の画面かと考えます。畳んだ後に読み返して、同じ実体が2通りで書かれていないか見る。

触っていない画面を確認範囲に入れない。 実装で裏を取り、更新や取り直しの対象に入っているかを確かめる。

6. 文面を渡す

投稿はしない。 貼る先と宛先はユーザーが決めます。

そのままコピーできる形で会話に出し、落とした情報があれば文面の外で伝える（「原因の詳細は省きました」等）。

出力の目安

文面は15行以内。段落4つと箇条書き1つで収まる
段落は主題ごとに1つ。1段落に2つの主題を詰めない
ユーザーへの補足は文面の外に置き、文面そのものには混ぜない

やってはいけないこと

PR 番号で節を分けること。読み手にとって意味を持たない
症状ごとの Before / After を並べた表を3つ以上置くこと。網羅はできるが全体像が消える
症状だけ書いて、どう対応したかを省くこと。原因が分からないと、読み手は似た症状を疑えない
内部の呼び名をそのまま出すこと（ explain_from_observables.md ）。読み手は画面しか見ていない
データが失われる系の症状を、表示の不具合と並べること。埋もれる
見出しと太字に依存した形で書くこと。貼る先が Markdown とは限らない
PR 本文だけを読んで畳むこと。本文が実態と食い違っていることがある
触っていない画面を確認範囲に入れること。実装で裏を取る
文面を投稿すること。貼る先と宛先はユーザーが決める
貼る先を確かめずに記法を決めること。記法を外すと記号がそのまま文字として出る。過去の投稿を参考にするならテキストではなく描画された姿を見る
同じ画面を文中と確認範囲で違う呼び方にすること。読み手は別の画面かと考える
差分・コミットハッシュ・型名・ファイルパスを文面に入れること

summarize-prs

Files1

SKILL.mdhome/.claude/skills/summarize-prs/SKILL.md

対象