pr-prep

プルリクエスト準備ワークフロー

使用しない場合

• 他の人の PR をレビューする場合（sanctum:pr-review を使用）
• コミットメッセージだけが必要な場合（sanctum:commit-messages を使用）

使用方法

変更をステージングし、PR の概要を作成するには、このスキルを使用します。リポジトリの状態と差分を記録するため、最初に Skill(sanctum:git-workspace-review) を実行します。

必須の進捗管理

開始前に、以下の手順の進捗項目を作成します。

1. pr-prep:workspace-reviewed
2. pr-prep:quality-gates
3. pr-prep:self-reviewed
4. pr-prep:changes-summarized
5. pr-prep:testing-documented
6. pr-prep:pr-drafted
7. pr-prep:content-verified

各セクションが完了したら、該当する項目を完了としてマークします。

ステップ 1：ワークスペースをレビューする（workspace-reviewed）

Skill(sanctum:git-workspace-review) が完了していることを確認します。最初のレビュー後に変更をステージングした場合は、スキルを再実行してコンテキストを更新します。

ステップ 2：品質ゲートを実行する（quality-gates）

プロジェクト固有のコマンド（例：make lint、make test）を使用して、フォーマット、リンティング、テストを実行します。続行する前に、すべての失敗を解決します。ローカルで実行できないタスクがある場合は、その理由と実施した代替検証を記録します。言語固有のコマンドと失敗時の対応については、modules/quality-gates.md に詳しく記載されています。

機能リファレンスの同期

プラグインファイル（plugin.json、skills、commands、 agents、hooks）が変更された場合は、make docs-sync-check を実行して、 book/src/reference/capabilities-reference.md が最新であることを確認します。 不一致が報告された場合は、続行する前に /sync-capabilities --fix を実行するか、リファレンスを手動で更新します。

ステップ 2.5：セルフレビュー（self-reviewed）

初めてこの変更を見るレビュアーのつもりで差分を読みます。これにより、スコープの逸脱、古いデバッグコード、不明瞭な変更などを、他の人が時間を費やす前に発見できます。

自動チェック：

# Check for debug statements left in
git diff --cached --name-only | xargs grep -nE \
  '(console\.log|print\(|debugger|TODO|FIXME|HACK|XXX)' \
  2>/dev/null || true

# Check for commented-out code blocks (3+ consecutive lines)
git diff --cached | grep -c '^+.*//.*[a-zA-Z]' || true

# Check for formatting-only commits mixed with feature work
git log --oneline $(git merge-base HEAD origin/master)..HEAD | \
  grep -iE '(fmt|format|lint|style|whitespace)' || true

追加バイアスの監査：

Skill(imbue:justify) を実行して追加バイアススコアを算出し、鉄則への準拠を確認します。スコアが YELLOW 以上の場合は、続行する前にフラグが付いた各シグナルを正当化します。RED または STOP の場合は、アプローチを再検討します。

手動検証：

• 差分全体を読む：すべての変更が明記された目標に役立っていますか？
• デバッグ用の記述や TODO マーカーが残っていない
• コメントアウトされたコードブロックがない
• フォーマット変更とロジック変更が混在していない
• スカッシュすべき fixup コミットがない
• 追加バイアススコアが GREEN、または YELLOW が正当化されている
• 鉄則への準拠：PASS（テストの改ざんなし）

問題が見つかった場合は、続行する前に修正します。

ステップ 3：変更を要約する（changes-summarized）

差分を新たに読み直すのではなく、まずアナライザーを実行します。

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/pr_prep_analyze.py" --base origin/main

このスクリプトはブランチで変更されたファイルとコミットを読み取り、ファイルを feature、test、docs、other に分類します。また、コミットの件名に ! の破壊的変更マーカーがあればフラグを付け、変更されたファイルの一覧から判定可能な品質ゲート（テストの変更、ドキュメントの変更、変更内容の説明）を報告し、マージ戦略を推奨して、説明文のひな形を出力します。パスのプレフィックスをレビュアーに対応付けるには --reviewer-map <json> を指定します。データとして利用するには --json を指定します。

ゲートが unknown（JSON では null）と出力された場合、スクリプトは何も評価していません。テスト、リンティング、型チェックは実行せず、リリースに関する判断も行いません。そのため、passes_checks と includes_breaking_changes は常に unknown と表示されます。unknown は「自分で確認する必要がある」という意味であり、合格として扱ってはいけません。passes_checks の答えを確認するのはステップ 2 です。

次に、ワークスペースレビューのメモとアナライザーのカテゴリを使って差分の要点を特定し、技術的な変更とその根拠を 2～4 段落にまとめます。破壊的変更、移行、ドキュメントの更新についても記載します。

Step 4: テストを記録する（testing-documented）

実行した各テストコマンドとその結果を列挙します。テストを省略した場合は、その理由と緩和策を記載します。

次のいずれかに該当する場合は、手動テスト計画を添付します。

• 変更に自動テストがありません。
• ユーザー向けまたは CLI 向けのフローに関わります。
• バグ修正です。再現、修正、検証の手順を記載します。再現手順では親コミットで失敗することを確認します。
• 外部コントラクトを変更します。

番号付きの手順で記述し、それぞれに期待される結果を記載します。期待される結果のない手順は、レビュアーが合否を判定できません。形式と例は modules/pr-template.md にあります。

Step 5: PR の下書きを作成する（pr-drafted）

テンプレートに事実の表（Who、Where、When）を記入し、続いて Why と What-and-how のセクション、次に Test plan と Checklist を記入します。タイトルは命令形にし、文脈から切り離されて git log に表示されても正しく読めるよう、内容が完結したものにします。

すべての PR で、表の 3 行すべてを記入します。該当しない行は削除せず（External: none、on merge のように）その旨を記載し、変更の影響範囲が省略されているのか、影響範囲がないのかを読者が判断できるようにします。

変更に応じて、課題への参照、スクリーンショット、移行ガイド、またはフォローアップ項目を追加します。テンプレートの構成、記入例、サイズのバリエーションは modules/pr-template.md にあります。この構成の決定とその根拠となる資料は docs/adr/0021-pr-descriptions-in-two-registers.md に記録されています。

Step 6: 内容の品質を検証する（content-verified）

下書きに Skill(scribe:slop-detector) の原則を適用します。PR の説明に、tier-1 の避けるべき語句（delve、comprehensive、leverage、utilize、robust、seamless）や、「I'd be happy to」「It should be noted.」のような定型句がないことを確認します。文章に AI への言及がなく、コマンド、数値、ファイル名などの証拠に基づいた主張のみであることを確認します。能動態を使い、文脈説明には文章を用いて、バランスの取れた構成を保ちます。

語彙の置き換え

• leverage または utilize は use に置き換えます。
• comprehensive は thorough または complete に置き換えます。
• robust は solid または reliable に置き換えます。
• facilitate は help または enable に置き換えます。
• streamline は simplify に置き換えます。

修正

説明に避けるべき表現が含まれている場合は、Skill(scribe:doc-generator) の原則を適用し、主張の根拠となる具体的な情報を示し、マーケティング表現を取り除いて、簡潔に記述します。

出力手順

最終的な PR の説明を指定されたパスに書き込み、確認のためファイルパスとその内容を表示します。

注意事項

PR の文章にツールや AI への言及を含めないでください。プロセスの途中で変更が必要になった場合は、品質ゲートを再実行してください。このスキルの対象は準備までです。変更のプッシュと PR の作成は、このワークフローの対象外です。

補助モジュール

• 進捗項目のパターン - sanctum の進捗項目の命名規則

トラブルシューティング

make や npm などのプロジェクト固有のコマンドが使用できない場合は、README を参照して環境設定を確認します。権限エラーが発生した場合は、ビルドディレクトリへの書き込み権限を確認します。手順が明確な出力なしに失敗した場合は、詳細フラグを付けてコマンドを再実行し、ログを確認します。

完了条件

• スキルが完了を宣言する前に、7 つの進捗項目（pr-prep:workspace-reviewed から pr-prep:content-verified まで）すべてに完了のマークが付いている
• 品質ゲート（フォーマット、リンティング、テスト）を実行して合格している。不合格項目があれば、先に修正してから進み、スキップしない
• アナライザーが unknown と出力したゲートは、すべて手動で判定している。unknown は何も評価されていないという意味であり、スクリプトはテスト、リンティング、型チェックを実行しないため、passes_checks と includes_breaking_changes は常にその状態になる
• PR の説明ファイルが指定されたパスに書き込まれ、確認用に内容が表示されている
• 3 行（Who、Where、When）すべてに記入されたファクト表があり、Where の External: 側も含まれている
• Why セクションには、一般的な主張ではなく、課題、数値、またはインシデントに基づく根拠がある
• Step 4 の 4 つのトリガーのいずれかが該当する場合、各ステップに期待される結果を記載した手動テスト計画が添付されている
• imbue:justify の加算バイアススコアが GREEN であるか、YELLOW の場合は、検出されたシグナルをそれぞれ明示的に正当化している
• PR の説明に、Tier 1 の避けるべき語句（delve、comprehensive、leverage、robust、seamless など）が含まれていない