triage-why-comments

コードコメントの評価は /review-code-comments がする。このスキルはその結果を受けて直す。 /review-code-comments は名前のとおり評価だけを返し、書き換えません。こちらは評価を持たず、書く・削る・直す・移すを実行します。

	/review-code-comments	このスキル
コードコメントの要否・移ろう WHY の判定	する	しない。結果を受け取る
インラインの [fyi] の要否	しない（対象外）	する
直す（書く・削る・直す・移す）	しない	する
投稿済みの [fyi] の直し方	しない	する

判定の正本はほかにもあります。どちらの WHY かは code_comments.md の「1年後も理由として成立するか」、[fyi] を置く行と書く中身は /update-pr-description の references/body.md （「差分から理由が読めない行には、その行へ [fyi] を置く」）です。ここには写さない。

このスキルが持つのは、2つの置き場を並べて見て、書く・削る・直す・移すを決めて直す手順です。 単独で呼ばれても、/update-pr-description の途中で呼ばれても、手順は同じです。片方だけを見ていると、同じ理由が両方に書かれていたり、どちらにも無かったりしても気づけません。

置き場	読まれる期間	置く WHY
コードコメント	コードが残る限り	恒久的な Why not（仕様・ドメインの制約、避けた落とし穴、外部システムの決まりごと、素直な書き方を採らなかった理由）
インラインの [fyi]	レビュー中だけ	一時的な WHY（バージョンの過渡期、移行の経緯、検査に合わせた書き換え、他の PR との関係）

なぜこの変更をしたか（Why）は、どちらにも置かずコミットメッセージへ置く。置き場ごとの分担は code_comments.md の「置き場ごとに、書くものを1つに決める」。

進め方

1. 2つの置き場を集める

• 対象の PR と base を特定し、作成者がユーザー本人かを確かめる（ no_operating_on_others_prs.md ）
• コードコメント: git diff <base>...HEAD の + 行からコメントを拾う（行頭が // か # のもの、JSDoc と doc コメント）。消したコメント（ - 行）も控える
• インラインの [fyi]: gh api repos/OWNER/REPO/pulls/<PR>/comments --paginate から、自分が投稿した [fyi] を拾う。path と line と original_line と commit_id も控える（ line が null なら差分から外れている）
• 同じファイルの近い行にあるものを組にして並べる。組にしないと、同じ理由の二重書きが見えない

2. 評価を集める（要るか・どちらの WHY か）

量産しない。 [fyi] もコードコメントも、増えるほど本当に要るものが埋もれる。既定は「置かない」で、残すものに理由を求める。

• コードコメント: /review-code-comments を呼び、PR の差分（ <base>...HEAD ）を対象に評価させる。返ってきた「削除 / 短縮 / 言い換え / PR の [fyi] へ移す」をそのまま手順3以降の入力にする。要否の基準をここで持ち直さない
• インラインの [fyi]: /review-code-comments の対象外なので、ここで見る。残すのは、その行だけを見たレビュアーが理由を当てられず、読むのが止まる行だけ。差分を読めば意図が分かる行、本文や近くの [fyi] と同じ理由、読み手が次に何もしない補足は削る
• 無いものを見つける。 差分を上から読み、理由が読めない行にどちらも無ければ書く候補にする（どちらに書くかは手順3）
• 消えたコメントを拾う。 手順1で控えた - 行を + 行と突き合わせ、+ 側に無いものを並べる。書き換えたものは - と + の両方に出るので、差には残らない。処理ごと消したなら消えてよいが、処理は残してコメントだけ消えていたら、その中身を上の2つと同じ基準に掛ける。要ると出たものだけ戻す
• 同じ理由は代表の1件にまとめる。 同じ理由で複数の行を直したなら、1件に置いて件数を添える（「このファイルの3か所」）

+ 行だけを見ると消えたコメントは見つかりません。 差分には残った処理が + として出るので、その手前のコメントが消えたことは - 行と並べて初めて分かります。

実際に、ストアの処理をオブジェクトの形から関数を呼ぶ形へ書き換えたとき、処理の手前にあったコメントが4ファイル・5件消えていました。+ 行だけでは見つからず、- 行を並べて見つかっています。

突き合わせに comm を使うなら LC_ALL=C で揃える（ verify_the_check_worked.md ）。

3. 1件ずつ、どちらの WHY かを判定して置き場と照らす

判定は手順2の評価（コードコメントは /review-code-comments の結果）と code_comments.md に当てる。ここで見るのは、判定の結果と今の置き場が合っているかだけ。

今の置き場	判定	直し方
コードコメント	恒久的	そのまま。/review-code-comments が削除・短縮・言い換えを返していれば、そのとおりに直す
コードコメント	一時的	コードから消し、その行へ [fyi] を置く（手順5）。手順2で要らないと評価されたなら、置かずに消すだけにする
[fyi]	一時的	そのまま。差分が動いて古くなっていれば直す（手順4）
[fyi]	恒久的	コードコメントへ移し、[fyi] は畳むか消す（手順6）
どちらにも無い	—	手順2で書く候補にした行だけ、判定した側に書く
両方にある	—	判定した側だけに残す

迷ったらコードコメントに寄せない。 コードコメントは消される機会がほとんど無いので、一時的な WHY を残すと将来のノイズになる。判定がつかないものは [fyi] に置き、報告で「判定に迷った」と添える。

4. 古くなった [fyi] を直す

差分が動くと、[fyi] の指す行が消えたり（ line が null ）、書いた中身が今のコードと合わなくなったりする。

• まだ読まれていないかを先に見る。リアクション・返信・Resolve のどれも無ければ、元のコメントを書き換える（ gh api -X PATCH repos/OWNER/REPO/pulls/comments/<id> ）。指す行が消えたなら、消して今の行へ置き直す
• 読まれた痕跡があれば、書き換えずに Hide（ Outdated ）で畳み、今の行へ新しく置く。見分け方と畳み方は keep_records_current.md の「判断が覆ったときは、書き換えずに残す」

5. コードから一時的な WHY を外す

• 消す前に、消す中身を控える。 消した後は思い出せなくなる（ code_comments.md の「削るときは、置くところまでを1つの作業にする」）
• コードを直してコミット・push する（ /commit-push ）。[fyi] は push したコミットを指すので、push の後で置く
• 置く [fyi] は、控えた中身を references/body.md の書き方（何を変えたか・なぜ要ったか・動作が変わるか）で書き直す。コードコメントの文面をそのまま貼らない

6. [fyi] から恒久的な WHY をコードへ移す

• コードコメントの書き方（Why not を厚く書く・書く前に書かない理由を探す）は code_comments.md に従う。[fyi] の文面をそのまま貼らない（レビュー向けの言い回しがコードに残る）
• コミット・push したら、元の [fyi] は手順4と同じ扱いで直す（読まれていなければ消す、読まれていれば畳む）

7. 残すものの表現を直す

要ると決めて残すものは、もっと伝わる言い方がないかを1件ずつ見て、あれば書き換える。

直す形	例
内部の呼び名	「行」「レコード」→ 画面や API で見える名前（ code_comments.md の「内部の呼び名で書かない」）
何が起きるかが決まらない語	「落ちる」「飛ぶ」→ 何がどうなるか（ explain_from_observables.md ）
比喩・言い換えの反復・冗長	/japanese-tech-writing に当てて直す
読み手に合わない中身	コードコメントに経緯やレビューの言い回しが残っている、[fyi] に何を変えたか・なぜ要ったか・動作が変わるかが揃っていない（ references/body.md ）
表記	複数行のコードコメントの行末の句点、GitHub の文章の1文ごとの改行（ code_comments.md や github_writing.md ）

直すのは中身を良くするときだけ。 言い回しの好みだけで書き換えると、差分とレビューの手間が増える。

8. 投稿する前に点検を通す

足す・書き換える [fyi] とコードコメントを、まとめて /japanese-tech-writing → /yomiyasu:yomiyasu に通す（ no_ai_style_writing.md の「文章の点検を通す場面と順序」）。1件が短くても対象になる。

9. 報告する

1件1行の表にする。動かしたものだけでなく、見てそのままにしたものの件数も書く（見たかどうかが読み手に分かるように）。

場所	動き	前	後	理由
path:line	移す	コードコメント	[fyi]	一時的な WHY（バージョンの過渡期）
path:line	書く	無し	コードコメント	ゼロ値が成功扱いになる落とし穴
path:line	削る	コードコメント	無し	関数名の言い換え
path:line	直す	「行を消す」	「一覧の項目を消す」	内部の呼び名

コミットのハッシュと、置いた・直した [fyi] の URL を添える（ report_formatting.md ）。

出力の目安

• 直すものが無いとき: 「コードコメント N 件・[fyi] M 件を見て、書く・削る・直す・移すものは0件」の1〜2行
• 直したとき: 上の表と、コミットのハッシュ・[fyi] の URL

やってはいけないこと

• 判定の基準をここに書き足すこと。コードコメントの評価は /review-code-comments、WHY の区別は code_comments.md、[fyi] の置き方は references/body.md が正本
• /review-code-comments を呼ばずに、コードコメントの要否を自分で決めること。評価と実行を分けた意味がなくなる
• コードコメントと [fyi] を別々に見ること。組にしないと二重書きと抜けが見えない
• + 行だけを見ること。処理を書き換えると、残った処理は + として出るのにその手前のコメントは - にしか出ない。並べないと消えたことが分からない
• 量産すること。要るかを先に決め、要るものだけを書く・残す。増えるほど本当に要るものが埋もれる
• 言い回しの好みだけで書き換えること。直すのは中身を良くするときだけ
• push の前に [fyi] を置くこと。まだ無いコミットは指せない
• 読まれた [fyi] を書き換えること。畳んで新しく置く
• 他人のコメントを直すこと。対象は自分が投稿したものだけ
• 置き場を移すときに、元の文面をそのまま貼ること。読み手が違うので書き直す

関連

• code_comments.md （コードコメントに何を書くか）: 恒久的か一時的かの判定の正本。本スキルはその結果に合わせて置き場を直す
• /review-code-comments （コードコメントの評価）: 評価はあちら、実行は本スキル。 本スキルは手順2であちらを呼び、返ってきた評価のとおりに直す
• /update-pr-description （PR 本文の更新）: 本文と差分の照合の前に本スキルを呼ぶ。[fyi] を置く行と書く中身は、あちらの references/body.md が正本
• keep_records_current.md （変えたら説明も直す）: 投稿済みの [fyi] を書き換えるか畳むかの判定
• verify_the_check_worked.md （検査が成立していたかを疑う）: 手順2で - 行と + 行を突き合わせるときの落とし穴。comm は照合順序がずれると空を返すので LC_ALL=C で揃える