pr-prep

PR 準備スキル

対象リポジトリの実際の慣例に合わせ、ブランチの内容を検証し、レビュー可能な PR 本文を作成して、外部へのコントリビューションを準備します。ワークフローを実行してください。ユーザーが正確なタイトル、本文、ベース、リモートを明示的に承認するまでは、何も提出しないでください。

重要な制約

• 理由：作業の重複を防ぎます。 コントリビューションをまとめる前に、オープン中およびマージ済みのイシュー／PRと、現在のデフォルトブランチを確認してください。
• 理由：対象リポジトリのルールを尊重します。 対象リポジトリの AGENTS.md、CONTRIBUTING.md、PR テンプレート、リリースノート、最近受け入れられた PR を読みます。ローカルの AgentOps の慣例が、上流のコントリビューションルールに優先することはありません。
• 理由：スコープを独立した単位に保ちます。 ブランチに無関係なテーマ、すでにマージされた変更、生成物によるノイズ、またはシークレットが含まれている場合は停止します。
• 理由：証拠の正確性を保ちます。 リポジトリで指定されたビルド、リント、テストのコマンドを実行してください。チェックが通っていない場合、完了としてマークしてはいけません。
• 理由：破壊的な履歴編集を避けます。 ユーザーが別途書き換えを許可しない限り、コミットの分割は提案のみにとどめます。
• 理由：外部への公開は状態を変更します。 まず下書きを作成して正確な内容を提示し、gh pr create の実行やプッシュの前に明示的な承認を得てください。

対象範囲とモード

外部リポジトリおよびオープンソースへのコントリビューション準備に使用します。通常の内部コミットや、AgentOps の main への直接リリース経路には使用しないでください。

折りたたまれた pr-research トリガーが上流調査モードに切り替えます。このモードでは、準備に先立って既存作業の調査、コントリビューションガイドラインの分析、マージ済み PR の調査、メンテナーのパターン調査を行います。その調査結果は .agents/research/YYYY-MM-DD-upstream-<slug>.md に保存します。

入力は、対象リポジトリ、現在のコントリビューションブランチ、任意のイシュー、任意の指定ベース／リモートです。準備の過程でローカルの成果物を作成してもかまいませんが、公開、履歴の書き換え、メンテナーへの連絡を行う権限が与えられるわけではありません。

ワークフロー

1. 既存作業を確認します。 上流のデフォルトブランチとリモートを特定します。対象の動作、シンボル、イシュー ID を使って、オープン中／クローズ済みのイシューと PR を検索します。競合するコントリビューションがある場合は、ユーザーが進め方を選ぶまで停止します。
2. 慣例を調べます。 リポジトリの指示、コントリビューション文書、PR テンプレート、CI 設定、変更履歴のポリシー、最近マージされた PR、コミットの件名を確認します。メンテナーが実際に使っているタイトル、本文、テストの慣例を正確に記録します。
3. 変更の独立性を検証します。 マージベースからの差分範囲を比較し、変更されたファイルとコミットを一覧表示して、動作ごとに分類します。無関係なファイル、シークレット、生成された成果物、デバッグ出力、ベースブランチにすでにある変更を削除するか、報告します。
4. ブランチを検証します。 対象リポジトリで文書化されているフォーマッター、リント、ビルド、テスト、およびコントリビューション固有のチェックを実行します。コマンド、終了ステータス、関連する結果を記録します。失敗したチェックは、下書きでも失敗として記載します。
5. コミットを分析します。 50 行未満かつ 4 ファイル以下の差分には、単一のコミットを推奨します。それ以外の場合は、commit-split-advisor.md に従います。提案ではファイルグループの順序を示し、各コミットがビルド可能な状態を保つようにします。書き換えは行いません。
6. PR の下書きを作成します。 .agents/pr-prep/YYYY-MM-DD-<slug>.md に、提案するタイトル、上流／ベース、関連イシュー、簡潔な背景／変更の概要、変更一覧、実行した証拠だけを含むテスト計画、互換性／ロールバックに関する注記、レビュー担当者に関係するリスクを記載します。上流のテンプレートに正確に従います。
7. 確認 — ユーザーによるレビュー必須。 タイトル、本文、ベース、リモート、ブランチ、検証結果、失敗または未テストのチェックを提示します。承認または修正を求め、返答を待ちます。無回答、「準備して」という依頼、または以前に付与されたプッシュ権限は、この PR を作成する承認にはなりません。
8. 承認後にのみ提出します。 HEAD が移動していた場合は、差分と検証を再確認してから、gh pr create --title <approved-title> --body-file <approved-file> --base <approved-base> を実行します。作成された URL を報告し、依頼がない限り PR にそれ以上の変更を加えません。

PR 本文の形式

## Summary
<what changed and why; 1-3 sentences>

## Changes
- <reviewable behavior or implementation point>

## Test plan
- [x] `<command>` — <result>
- [ ] <not run> — <reason>

Fixes #<issue>

チェック済みボックスは、実行済みの PASS の証拠にのみ使用してください。失敗またはスキップしたチェックは表示したままにしてください。上流のポリシーで許可される場合は、末尾にクローズキーワードを記載してください。

出力仕様

• 成果物ディレクトリ： ローカルのレビュー用ドラフトには .agents/pr-prep/、任意の上流調査には .agents/research/ を使用します。現在の Git ブランチがコードの成果物です。
• ファイル名の規則： YYYY-MM-DD-<contribution-slug>.md。無関係なドラフトを上書きしないでください。
• シリアライズ／スキーマ形式： 上流の PR テンプレートに沿った Markdown とし、タイトル、リモート／ベース、概要、変更点、テスト計画、リスク、課題との関連を含めます。
• バリデーターコマンド： 承認を依頼する前に、bash skills/pr-prep/scripts/validate.sh、対象リポジトリで文書化されているチェック、git diff --check、およびリポジトリに適したシークレットスキャンを実行します。
• 後続への引き継ぎ： まずユーザーのレビューに使用し、明示的な承認後に限り、gh pr create --body-file と上流のメンテナーに引き継ぎます。

品質基準

• 慣例に準拠： タイトル、テンプレート、コミットの形式、チェックが上流の慣例に沿っています。
• 分離： 変更したすべてのファイルが、ひとつの貢献内容に沿っています。
• 証拠に基づく： テスト計画で、合格、失敗、未実施のチェックを区別しています。
• レビューしやすい： 根拠、動作、リスク、互換性が簡潔かつ明確です。
• 安全： シークレット、無関係な変更、破壊的な書き換え、暗黙の送信がありません。
• 再現可能： 正確なブランチ範囲、コマンド、ベース、リモート、ドラフトのパスが記載されています。

例

ユーザーの依頼： 「このブランチを上流への PR 用に準備してください。」

上流のルールと過去の作業を調査し、ブランチを検証して、ローカルの PR ドラフトを作成したら、レビューのチェックポイントで停止します。

ユーザーの依頼： 「先ほど承認したドラフトを使って PR を送信してください。」

ドラフトと HEAD が承認時の状態に一致することを確認してから、その PR を作成し、URL を報告します。

トラブルシューティング

問題	対応
競合する PR が存在する	重複する内容を示し、ユーザーの指示を待ちます
ブランチに複数のテーマが混在している	分割するグループを提案します。許可なく書き換えないでください
必須チェックが失敗する	ドラフトに失敗状態を残し、準備完了であるかのように示さないでください
上流のテンプレートがない	最近マージされた PR から推測し、その推測を明記します
承認後に HEAD が変わった	証拠を再生成し、再度承認を依頼します

参考資料

• pr-prep.feature — 実行可能な動作仕様
• commit-split-advisor.md — ビルド可能なコミット分割案
• case-study-historical-context.md — 貢献に関する過去の背景
• lessons-learned.md — 再利用可能な準備の教訓
• package-extraction.md — パッケージ抽出のガイダンス