reply-and-review-discipline

返信とレビューの規律

他の人のスレッドでは、読者はざっと目を通すだけでコードを知らず、そこに書かれた内容はすべてユーザー名義で公開されます。まず平易な言葉を使い、矢印付きの注記を添えて読者自身のログ行を示します。報告に答えがない場合に限り質問し、PR ではユーザーが公開する保留中のレビューを 1 件だけにします。

これらのルールは、自分が作成したものではないスレッドに書き込むすべてのセッションに適用されます。対象は、イシューへの返信、または他の人の PR のレビューです。ユーザー自身の PR またはイシューでは、/pr-and-issue-discipline スキルを適用します。その Readability ルールと秘匿ルールは、ここでも変更なく適用されます。詳しくはそちらに記載されています。

インストールされている場合、/unslop はすべての返信とステージ済みコメントに対して最後に実行されます。ユーザー名義で公開されるため、AI だとわかる表現は使いません。

適用する場面

• イシューの報告者や外部のコントリビューターに返信するとき
• ユーザーのアカウントで他の人の PR をレビューするとき

Issue 報告者への返信：まずは平易な説明から

外部のコントリビューターへの Issue 返信は、コードを知らず、スレッドをざっと読む人の目に触れます。単独で意味が通じる平易な説明を書いてください。平易な説明だけでは伝えられない情報がある場合に限り、読み飛ばしても負担にならないよう折りたたんだ技術的な説明を加えます。すべてを平易な言葉で伝えられるなら、返信は平易な説明だけで十分です。

他の人の PR に付けるレビューコメントは、以下の「各コメントのルール」に従い、このセクションの語調だけを取り入れます。レビューの要約には、そちらで定める独自の形式があります。

冒頭は報告内容で決まります：書き始める前に、報告者のログを読んでください。報告ですでに答えが示されていることは質問しません。そのため、原因が見えている場合は診断と手順から、原因が不明な場合は質問から始まります。質問から始めることを既定にするのは、サンプルが避けようとしている失敗です。

cause visible in the log                    cause not in the log
------------------------------------        ------------------------------------
## What the report shows                    ## Questions   (3 at most; say which helps most)
   their log lines, with arrow notes        ## What the report shows
## What to do                                  their log lines, with arrow notes
   1. ...  2. ...  3. ...                      a guess, labeled a guess, last
   one fallback line: what to paste next    <details> Technical details </details>   (only when it adds something)

どちらの形式の完全なサンプルと、2 言語でのレイアウトについては、references/issue-replies.md を参照してください。

• 原因が見えている場合：まず ## What the report shows、続けて番号付きの ## What to do。 読者自身のログ行に矢印付きの注釈を添えて診断を示し、番号付きの各手順には、該当するものがあれば正確なクリック手順またはコマンドを記載します。第 1 部の最後に、手順で解決しなかった場合に何を貼り付ければよいかを伝えるフォールバックの一文を置き、## Questions の見出しは付けません。
• 原因が不明な場合：最初に ## Questions。 診断が回答に本当に左右される場合に限り、## Questions の見出しを付けます。質問形式で尋ねてください。番号付きリストは最大 3 つとし、どの質問が最も役立つかも伝えます。
  • 該当するものがあれば、正確なクリック手順またはコマンドを示します。
  • 「必要なこと」ではなく「役立つこと」と表現します。報告者はあなたに協力してくれています。読者はリストを読んだところで離れてもかまいません。
• 第 1 部は平易な言葉で書き、平易な言葉だとは決して言いません（見出しのルールは「読みやすさのルール」に従います）。
  • 読者が何をして、何を目にしているかを述べます。「tombstoned server entry」ではなく「削除したサーバー」のように表現してください。仕組みを平易な名前で呼べない場合は、仕組みに名前を付けず、その影響を示します。
  • 読者自身のログ行を引用し、言い換えずに矢印付きの注釈を添えます。
• 第 2 部は技術的な解説を折りたたんだもので、情報を加える場合に限ります。 /pr-and-issue-discipline スキルにある PR 本文の第 2 部と同じ折りたたみ形式を使い、要約行は各言語のもの（Technical details、Détails techniques）にします。
  • <details> ブロック内には、仕組みの名称、ログ行とコードパスの対応、ドキュメントへのリンク、そしてスレッドを読み返す将来のメンテナーに役立つ情報を記載します。第 1 部の内容は第 2 部に依存しません。
  • すべてを平易な言葉で説明できる返信には、第 2 部を設けません。原因が見えている場合のサンプルにはありません。一方、リクエスト途中のサンプルには、バッファーサイズとタイムアウトがログの停止位置を説明するため、第 2 部があります。
• 推測は第 1 部の最後に置き、推測であることを明記します。 回答を待つ前に読者の方向を決めつけることなく、やり取りを 1 往復減らせます。
• まず報告者の言語、次に英語。 報告者が別の言語で書いている場合、または貼り付けたテキストから別の言語が分かる場合（ローカライズされたエラーメッセージや UI ラベルなど）は、返信に両方の言語を含めます。報告者の言語で全文を書き、その後に英語で全文を書きます。
  • それぞれのパートは単独で完結させ、返信に折りたたみ部分がある場合は、各パートにそれぞれ設けます。どちらのパートも、もう一方の要約にはしません。
  • 2 つのパートは 1 つのコメント内に置き、その間に区切り線を入れます。レイアウトは references/issue-replies.md を参照してください。
• 見出しと語調はリポジトリの慣例に従いますが、返信の読みやすさはそれに左右されません。 メンテナーが「テンプレートより文章」を推奨している場合は見出しを省き、語調を柔らかくします。それでも内容と順序は変えず、ざっと読めるようにします。文章が長すぎないかは返信ごとに判断し、テキストの壁にはしません。
• 「読みやすさのルール」と機密情報の削除ルールは、2 言語の返信の両方のパートにそのまま適用されます。

他の人の PR をレビューする：保留中のレビューは 1 件

エージェントはユーザーのアカウントでレビューするため、公開するのはユーザー自身です。ステージングされたレビューをユーザー自身が公開するか、ユーザーが決めた判定を投稿するようエージェントに指示します。すべてのコメントは、ユーザーが編集して公開するための 1 件の保留中レビューにまとめます。他の人の PR に単独のコメントを投稿してはいけません。即時にユーザー名で、編集できないまま公開されてしまいます。

読み始める前に、PR ごとに一度だけ観点を選びます。 推奨内容を決めるのは PR の作成者ではなく、リポジトリの所有者です。

• ユーザーが所有するリポジトリ、またはユーザーが所有する組織のリポジトリ： ユーザー自身の PR と同様に、これらのスキルの基準をすべて適用します。/rubber-duck-review スキルは、確認を求めず、インストール済みのすべての ## Review Criteria セクションを組み込みます。すべてを推奨します。
• ユーザーが所有していないリポジトリ： まずそのリポジトリの慣例を優先します。同僚の PR にこれらの基準のどれを適用するかは、ユーザーが決めます。正確性の観点を推奨し、残りは選択肢として提示します。

1. 候補を集めます： /rubber-duck-review スキルのコンパニオンスキル確認手順に従って見つけた、## Review Criteria セクションを宣言しているインストール済みの各スキル、そのスキル自体による PR の差分の読み取り専用クロスモデルレビュー、および PR が作業中の文章（ページ、コメント、説明）に触れる場合は /working-text を含めます。

2. まずメモリを読みます： セッションで利用できるメモリ（インデックス、メモリシステムが保持する場所、およびこのプロジェクトのメモリ）を確認します。このリポジトリに関する継続的な修正指示、前回同様の PR をレビューした際にユーザーが伝えたルール、手作業で実装するよりユーザーが好むライブラリなどは、それぞれ観点を加えたり、外したり、推奨を調整したりします。

3. 推奨を最初に、一度だけ確認します。 ダイアログ外のテキストは失われるため、各観点を選ぶ理由もダイアログ内に含めます。

   Lenses for PR #123 on octocat/fetcher, a repository you do not own (adds a retry loop in src/fetch.ts and a page docs/retries.md). Apply which?
   
   [x] /rubber-duck-review on the PR diff (Recommended)   a second model, read-only, before staging
   [x] /never-twice criteria (Recommended)                the retry loop repeats a fix from PR #98
   [ ] /code-standards criteria                           their repository, their standards; memory: prefer a library
                                                          over hand-rolling, if you hold this PR to it
   [ ] /working-text                                      docs/retries.md is a new page
   [ ] /no-invalid-states                                 no lifecycle flags or repeated guards in the diff
   [ ] /verify-with-controls                              the body claims no zero, alarm, or success reading
   

4. PR の全リビジョンを通して、選択した内容を維持します。 この PR に対する /rubber-duck-review のレビューでは、インストール済みのすべてのセクションではなく、ユーザーがここで選んだ ## Review Criteria セクションだけを展開します。そのスキルの全セクションを適用するルールは、ユーザー自身の変更に対するものであり、この選択によって適用範囲が決まります。続いて、PR にリンクされたドキュメントとコードを読み、その後で初めてレビューを書きます。

ステージング： JSON ボディは 1 つだけにし、その中にヘッドコミットを含めます。event フィールドは含めません。commit_id はファイル内に記述します。--input を使う場合、-f フィールドは URL クエリ文字列に送られます。

ファイルはハーネスのファイル書き込みツールで作成し、ヘッド SHA をあらかじめ含めておきます。コメント本文には、シェルのヒアドキュメントで実行されてしまうバッククォートが含まれることがあり、一部のサンドボックスではヒアドキュメント、trap、またはコマンドに連結された変数が拒否されます。/pr-and-issue-discipline スキルの PR 本文のフォールバックと同様に、各手順で単独のコマンドを 1 つだけ実行し、削除は最後に独立したコマンドとして実行します。

複数行にわたる指摘は、範囲全体に start_line と line を指定してアンカーを設定します。start_side と side には、該当する行がある差分側を指定します。新しいファイルの行には RIGHT、削除された範囲には LEFT を指定します。1 行だけで指摘全体を表せる場合に限り、単一行にアンカーを設定します。

gh pr view <n> --repo <owner>/<repo> --json headRefOid -q .headRefOid                          # 1. the head SHA, for commit_id below
mktemp -d /tmp/pr-review-XXXXXX                                                                   # 2. prints e.g. /tmp/pr-review-Kq3mZp; copy the printed path by hand
# 3. write /tmp/pr-review-Kq3mZp/review.json with the harness's file-writing tool:
#    {
#      "commit_id": "<head SHA>",
#      "comments": [
#        {"path": "src/metrics.ts", "line": 42, "side": "RIGHT", "body": "Review summary (copy into the summary box)\n\n[comment, not approve yet]\n\n**Works:** ...\n**Blocks:** ..."},
#        {"path": "src/metrics.ts", "start_line": 84, "start_side": "RIGHT", "line": 88, "side": "RIGHT", "body": "[blocking] The two headline metrics disagree on answers that cannot be parsed. Count them the same way in both."}
#      ]
#    }
gh api -X POST repos/<owner>/<repo>/pulls/<n>/reviews --input /tmp/pr-review-Kq3mZp/review.json --jq .id   # 4. no "event": stays pending
rm -rf /tmp/pr-review-Kq3mZp                                                                      # 5. its own command, whatever gh returned

修正： GitHub では、PR ごとに投稿者 1 人につき保留中レビューを 1 件だけ保持できるため、2 回目の POST は失敗します。ユーザーがウェブ UI で編集している可能性があるため、保留中レビューのコメントを現在の状態で読み取り、その内容から全コメントを作り直します。その後、保留中レビューを削除し、残っていないことを確認してから再作成し、ID が変わったことをユーザーに伝えます。

# --paginate: a PR with many reviews spreads them over pages, and the pending one is the newest
gh api --paginate repos/<owner>/<repo>/pulls/<n>/reviews --jq '.[] | select(.state == "PENDING") | .id'   # the id to delete
gh api --paginate repos/<owner>/<repo>/pulls/<n>/reviews/<id>/comments --jq '.[] | {path, start_line, start_side, line, side, body}'   # the current text, web edits included, with each anchor's range; rebuild from this (position alone would collapse a ranged comment to one line)
gh api -X DELETE repos/<owner>/<repo>/pulls/<n>/reviews/<id>
gh api --paginate repos/<owner>/<repo>/pulls/<n>/reviews --jq '.[] | select(.state == "PENDING") | .id' | wc -l   # must print 0 before the new POST

判定は常に PR 上に記録し、ドキュメントには記録しません。

• 要約は、最初に変更された行に付けるステージ済みのインラインコメントです。見出しは Review summary (copy into the summary box) とし、その後に角括弧で囲んだ推奨（[LGTM]、[comment, not approve yet]、[request changes]）、続いて Works: と Blocks: の行だけを記載します。3行目が必要になるような細かな指摘は、そもそもステージしません。ウェブダイアログでは API に設定したレビュー本文が消えるため、ユーザーはこれを要約ボックスに貼り付けます。
• ユーザーが判断し、投稿するようエージェントに指示した判定は、ステージせずに event（APPROVE、REQUEST_CHANGES、または COMMENT）と body を指定して直接送信します。その指示をもって投稿とします。指示がなければ、すべて保留のままです。
• ユーザーへの報告は、推奨を伝えるチャット1行だけです。指摘事項の文書も、コピー＆ペースト用ファイルも、ダッシュボードの行も作成しません。

各コメント：

• できるだけ短く、平易な英語で1文または2文にします。 投稿者向けのヒントを角括弧で示して始め（[blocking]、[small ask]、[question]）、次に求める変更を具体的に記します。背景説明や、コードの動作の言い換えは不要です。適切な例：「[blocking] The linked comment has only headline and per-type tables, not the 100-task paired table the body promises. Please post it or link to it.」
• 人間らしい平易な表現にします。 Replies セクションの言葉遣い（平易な表現で、内部名を使わないもの）を使い、2部構成や言語の組み合わせは使いません。不適切な例：「PARSING_ERROR maps to COULD_NOT_EXTRACT_ANSWER, which is trainable, so the rollout arrives as a CompletedRollout with reward 0」。コメント1件につきコード識別子は最大1つ、比較は1つまでとし、数字を連鎖させません。技術的な詳細は、著者が対応するために必要な場合に限ります。
• 再レビューでは、未解決または一部解決の項目だけをコメントとしてステージします。 著者が対応した項目には個別のコメントを付けず、解決済みの項目は要約に1行でまとめてもかまいません。
• 動作、信頼性、または明記された事実の正しさを変える点だけを扱います。 ユーザーから依頼がない限り、テストカバレッジ、YAGNI、整理整頓に関する細かな指摘はステージしません。投稿者の多くはそうした指摘を削除するため、ステージしても編集の手間が増えるだけです。
• Windows でのみ発生する問題（改行コードの変換、パス区切り文字など）は、リポジトリが Windows をサポートしている場合に限り指摘します。CI マトリックス、ドキュメント、または課題にその記載がある場合が該当します。大文字と小文字を区別しないファイルシステムは macOS のデフォルトでもあるため、こちらは指摘対象のままです。
• 編集者を伏せるルールは適用されます。ステージ済みのコメントはユーザーの名前で投稿されます。