pr-report

PR レポートスキル

PR、ブランチ、大規模なコントリビューションについて、メンテナー向けのレビューを作成します。

基本方針：

• 評価する前に変更内容を理解する
• 差分だけでなく、実際に構築されるシステムを説明する
• アーキテクチャ上の問題と、製品スコープに関する異議を分ける
• 曖昧な印象ではなく、具体的な推奨事項を示す

使用する場面

ユーザーから次のような依頼があった場合に、このスキルを使用します。

• 「このPRを詳しくレビューして」
• 「このコントリビューションについて説明して」
• 「このPRのレポートまたはウェブページを作って」
• 「この設計を類似システムと比較して」
• 「これをマージすべき？」

出力

一般的な出力：

• tmp/reports/... に保存する単独のHTMLレポート
• report/ または指定された別のフォルダーに保存するMarkdownレポート
• チャットでの簡潔なメンテナー向け要約

ユーザーがウェブページを求めた場合は、セクションが明確で視覚的な階層が読みやすい、洗練された単独のHTML成果物を作成します。

このスキルに含まれるリソース：

• 視覚的な方向性とレポートの提示ルールについては、references/style-guide.md を参照してください
• 再利用可能な単独のHTML/CSSスターターについては、assets/html-report-starter.html を参照してください

ワークフロー

1. 対象を取得し、位置づける

可能であれば、GitHubのPRページだけでなく、ローカルコードを使って作業します。

以下を収集します。

• 対象のブランチまたはワークツリー
• 差分の規模と変更されたサブシステム
• 関連するリポジトリのドキュメント、仕様、不変条件
• PRの本文または設計ドキュメントに記載された、コントリビューターの意図

まず、次の問いに答えます。この変更は何を実現しようとしているのか？

2. システムのメンタルモデルを構築する

ファイルごとのメモだけで終わらせないでください。設計を再構築します。

• どのような新しいランタイムや契約が存在するか
• どのレイヤーが変更されたか：データベース、共有型、サーバー、UI、CLI、ドキュメント
• ライフサイクル：インストール、起動、実行、UI、障害、無効化
• 信頼境界：どのコードが、どの権限で、どこで実行されるか

大規模なコントリビューションでは、システムを基礎から解説するチュートリアル形式のセクションを含めます。

3. メンテナーの視点でレビューする

指摘事項を最初に示し、重大度順に並べます。

優先する項目：

• 動作の後退
• 信頼やセキュリティの欠陥
• 誤解を招く抽象化
• ライフサイクルおよび運用上のリスク
• 解消が難しい結合
• テストの不足、または検証できない主張

可能な限り、具体的なファイル参照を必ず記載します。

4. 異議の種類を区別する

懸念が次のどれに該当するかを明確にします。

• 製品の方向性
• アーキテクチャ
• 実装品質
• 展開戦略
• ドキュメントの正確さ

アーキテクチャ上の異議を、スコープに関する異議の中に隠さないでください。

5. 必要に応じて外部の先例と比較する

コントリビューションでフレームワークやプラットフォームの概念が導入されている場合は、類似するオープンソースシステムと比較します。

比較する際は：

• 公式ドキュメントまたはソースコードを優先する
• 拡張境界、コンテキストの受け渡し、信頼モデル、UIの所有権に焦点を当てる
• 類似点を並べるだけでなく、得られる教訓を抽出する

比較に役立つ質問：

• ライフサイクルの所有者は誰か？
• UI構成の所有者は誰か？
• コンテキストは明示的か、それとも暗黙的か？
• プラグインは信頼されたコードか、それともサンドボックス化されたコードか？
• 拡張ポイントには名前と型が定義されているか？

6. 実行可能な推奨事項を示す

「マージする」または「マージしない」だけで終わらせないでください。

次のいずれかを選びます。

• 現状のままマージする
• 具体的な再設計の後にマージする
• 特定の部分を活かす
• 設計調査として維持する

却下または範囲を縮小する場合は、何を残すべきかを示します。

推奨事項の分類例：

• プロトコル／型モデルは維持する
• UI境界を再設計する
• 初期段階の対象範囲を絞る
• サードパーティコードの実行を延期する
• まずホスト所有の拡張ポイントモデルをリリースする

7. 成果物を作成する

推奨レポート構成：

1. エグゼクティブサマリー
2. PR が実際に追加するもの
3. チュートリアル：システムの仕組み
4. 強み
5. 主な調査結果
6. 比較
7. 推奨事項

HTML レポートの場合：

• 意図的なタイポグラフィと色使いにする
• 長いレポートでもナビゲーションしやすくする
• 明確なセクション見出しと小さな参照ラベルを活用する
• ありきたりなダッシュボード風のスタイルは避ける

一から作成する前に、references/style-guide.md を読んでください。 すぐに使える洗練されたひな形が役立つ場合は、assets/html-report-starter.html から始め、プレースホルダーの内容を実際のレポートに置き換えてください。

8. 引き渡し前に検証する

次の項目を確認してください：

• 成果物のパスが存在する
• 調査結果が実際のコードと一致している
• 生成された出力に、指定された禁止文字列が含まれていない
• テストを実行していない場合は、その旨を明記する

レビューのヒューリスティック

プラグインとプラットフォームに関する作業

次の点に特に注意してください：

• 実行時に信頼されたホストプロセスを実行しているのに、ドキュメントではサンドボックス化を謳っている
• React のコンテキストを持ち込むために、モジュールのグローバル状態を使用している
• レンダリング順序への隠れた依存関係がある
• プラグインが明示的な API を使わず、ホストの内部実装に踏み込んでいる
• 実際には完全に信頼されたコードの上にポリシーラベルを付けただけの「機能」

良い兆候

• レイヤー間で共有される型付きコントラクト
• 明示的な拡張ポイント
• ホストが管理するライフサイクル
• 実態に即した信頼モデル
• 今後拡張できる余地を残した、範囲を絞った初回展開

最終回答

チャットでは、次の内容を要約してください：

• レポートの場所
• 全体的な評価
• 主な理由を1つか2つ
• 検証またはテストを省略したかどうか

チャットでの要約は、レポート自体より短くしてください。