pr-review

スコープ重視の PR レビュー

規律ある方法でプルリクエスト／マージリクエストをレビューします。元の要件に照らして検証し、スコープの逸脱を防ぎ、スコープ外の指摘事項は検出したプラットフォームの Issue に振り分けます。

プラットフォームは leyline:git-platform によって自動検出されます。 GitHub では gh、GitLab では glab を使用します。セッションのコンテキストで git_platform: を確認してください。

基本原則

PR レビューでは、コードの完璧さではなく、スコープへの準拠を検証します。

目標は、実装が明示された要件を満たし、リグレッションを引き起こしていないことを検証することです。スコープを超えた改善は、今後の PR に含めます。

使用する場面

• 機能ブランチをマージする前
• チームメイトの PR をレビューするとき
• レビューを依頼する前に、自分の作業を検証するとき
• レビュー中に見つかった改善案をバックログにまとめるとき

使用しない場面

• PR の準備 — 代わりに pr-prep を使用してください
• 詳細なコードレビュー — pensive:unified-review を使用してください
• PR の準備 — 代わりに pr-prep を使用してください
• 詳細なコードレビュー — pensive:unified-review を使用してください

スコープ分類フレームワーク

各指摘事項を PR の明示されたスコープに照らして分類する方法： modules/scope-classification.md。

ワークフロー

フェーズ 1：スコープの基準を確立する

コードを確認する前に、この PR で何を実現するのかを把握します。

注： バージョン検証（フェーズ 1.5）は、スコープの確立後、コードレビューの前に実施します。詳細は modules/version-validation.md を参照してください。

以下の順序でスコープの根拠となる情報を検索します：

1. Plan ファイル： 最も信頼性の高い情報です（まず spec-kit の場所を確認し、次にルートを確認します）

   # Spec-kit feature plans (preferred - structured implementation blueprints)
   find specs -name "plan.md" -type f 2>/dev/null | head -1 | xargs cat 2>/dev/null | head -100
   # Legacy/alternative locations
   ls docs/plans/ 2>/dev/null
   # Root plan.md (may be Claude Plan Mode artifact from v2.0.51+)
   cat plan.md 2>/dev/null | head -100
   

   確認： コマンドに --help フラグを付けて実行し、利用可能であることを確認します。

2. Spec ファイル： 要件の定義です（まず spec-kit の場所を確認します）

   find specs -name "spec.md" -type f 2>/dev/null | head -1 | xargs cat 2>/dev/null | head -100
   cat spec.md 2>/dev/null | head -100
   

   確認： コマンドに --help フラグを付けて実行し、利用可能であることを確認します。

3. Tasks ファイル： 実装チェックリストです（まず spec-kit の場所を確認します）

   find specs -name "tasks.md" -type f 2>/dev/null | head -1 | xargs cat 2>/dev/null
   cat tasks.md 2>/dev/null
   

   確認： コマンドに --help フラグを付けて実行し、利用可能であることを確認します。

4. PR／MR の説明： 作成者の意図です

   # GitHub
   gh pr view <number> --json body --jq '.body'
   # GitLab
   glab mr view <number> --json description --jq '.description'
   

   確認： コマンドに --help フラグを付けて実行し、利用可能であることを確認します。

5. コミットメッセージ： 段階的な判断の記録です

   # GitHub
   gh pr view <number> --json commits --jq '.commits[].messageHeadline'
   # GitLab
   glab mr view <number> --json commits
   

   確認： コマンドに --help フラグを付けて実行し、利用可能であることを確認します。

出力： スコープを明確に示します：

「この PR は plan.md に記載されたとおり、[機能 X] を実装します。要件は次のとおりです：

1. [要件]
2. [要件]
3. [要件]」

スコープの根拠となる情報が見つからない場合は、プロセス上の問題として指摘します。ただし、PR の説明を基準としてレビューを続けてください。

フェーズ 2：変更内容を収集する

# GitHub
gh pr diff <number> --name-only
gh pr diff <number>
gh pr view <number> --json additions,deletions,changedFiles,commits

# GitLab
glab mr diff <number>
glab mr view <number>

確認： コマンドに --help フラグを付けて実行し、利用可能であることを確認します。

フェーズ 3：要件を検証する

詳細なコードレビューの前に、スコープが網羅されているかを確認します：

• 各要件に対応する実装がある
• 要件の漏れがない
• 実装が要件を超えていない（過剰設計の兆候）

フェーズ 1.5：バージョン検証（必須）

コードレビューの前に、バージョン検証を実施してください。

詳細な検証手順については、modules/version-validation.md を参照してください。

クイックリファレンス：

1. 検証をスキップする要求があるか確認します（--skip-version-check、ラベル、または PR マーカー）
2. PR の差分でバージョン関連ファイルが変更されているかを検出します
3. 変更されている場合は、プロジェクト固有の検証を実施します：
   • Claude マーケットプレイス：marketplace.json と plugin.json のバージョンを確認
   • Python：pyproject.toml と version を確認
   • Node：package.json と package-lock.json を確認
   • Rust：Cargo.toml と Cargo.lock を確認
4. CHANGELOG に新しいバージョンの項目があることを確認します
5. README／ドキュメントにバージョンへの言及があるか確認します
6. 指摘事項を BLOCKING（スキップされた場合は WAIVED）として分類します

メンテナーによって明示的に免除されない限り、バージョンの不一致はすべて BLOCKING です。

フェーズ 3.5：PR の品質チェック

コードを詳しく確認する前に、modules/pr-hygiene.md にある原子性、エージェントのキュレーション、セルフレビューのチェックを実施し、同ファイルの重大度表に従って指摘事項を分類します。

フェーズ 4：スコープコンテキストを踏まえたコードレビュー

変更されたファイルに対して pensive:unified-review を使用します。コメントの品質評価については、modules/comment-guidelines.md を参照してください。

重要： 各指摘をスコープのベースラインに照らして評価してください。

**Verification:** Run the command with `--help` flag to verify availability.
Finding: "Function X lacks input validation"
Scope check: Is input validation mentioned in requirements?
  - YES → IN-SCOPE
  - NO, but it's a security issue → BLOCKING
  - NO, and it's a nice-to-have → BACKLOG

確認： --help フラグを付けてコマンドを実行し、利用可能であることを確認してください。

フェーズ 4.5：追加バイアスの監査

PR の変更に対して Skill(imbue:justify) を実行し、 AI による追加バイアス、テストロジックの改ざん、不要な 複雑さを検出します。

主な確認項目：

1. 追加バイアススコア：正当な理由がないのに 追加／削除の比率が高い（>5:1）変更を指摘する
2. 鉄則の遵守：壊れた実装に合わせるためにテストのアサーションが 弱められていないことを確認する
3. 最小限の介入：変更された各ファイルが必要であり、 変更が最小限の修正であることを確認する

スコープの枠組みに基づいて justify の指摘を分類してください：

Justify シグナル	想定される分類
テストロジックの改ざん	BLOCKING
追加バイアスが高く、正当な理由がない	IN-SCOPE
時期尚早な抽象化	SUGGESTION
互換性シム	BACKLOG

追加バイアススコアと鉄則の遵守状況を フェーズ 6 のレポートに含めてください。

フェーズ 4.6：不変条件の競合検出

PR が既存の設計上の不変条件に触れているかどうかを確認します。 これは判断が必要な問題で、モデルは非常に頻繁に誤ります。 競合を黙って受け入れたり拒否したりせず、人間によるレビューのために 表面化させてください。

簡易検出ヒューリスティック：

1. 変更されたファイルが、これまで相互作用していなかった モジュールの境界をまたいでいますか？
2. 既存のパターンと並行して新しいパターンを導入していますか （同じことを行う方法が 2 つになる）？
3. インターフェース／型／スキーマのファイルの形が変わっていますか？
4. データフローの方向が変わっていますか？
5. ADR に記録された決定に矛盾していますか？

# Check for structural pattern changes
git diff --name-only HEAD...origin/master 2>/dev/null \
  | rg "(interface|types|schema|model|base|core|contract)" \
  || git diff --name-only HEAD...origin/master 2>/dev/null \
  | grep -E "(interface|types|schema|model|base|core|contract)"

競合が検出された場合：

解決してはいけません。特別なカテゴリとしてレポートに追加してください：

カテゴリ	定義	対応
INVARIANT	変更が既存の設計上の決定と競合している	3 つの選択肢を分析し、人間にエスカレーションする

不変条件の競合ごとに、次の内容を提示してください：

1. 不変条件：設計上の決定の名称と、その決定がなされた理由 （利用可能な場合は ADR を参照）
2. 競合：この PR が行う、決定と衝突する内容
3. 選択肢 A、維持：この変更をマージしない； 不変条件は他の箇所で効果を発揮する
4. 選択肢 B、重ねる：洗練されていないことを受け入れて 現状のままマージする；すべての機能が洗練されている必要はない
5. 選択肢 C、改訂：不変条件が誤っている； 再設計する場合の案を示す

分類： INVARIANT の指摘は、コードが誤っているからではなく、 判断に人間の意見が必要だから、常に BLOCKING です。 3 つの選択肢のどれが適切かを決定できるのは、人間の レビュアーだけです。

--hold-insights を指定した場合： 同じ保留の手順を、 記録された不変条件と競合するものだけでなく、変更の方向性、 アーキテクチャ、または差分から答えが出ない疑問に関する すべての指摘に適用します。チャットで提示してから、 バックログ項目に対してフェーズ 5 で使うプロンプトで尋ねます： 「方向性と設計に関する所見が N 件あります。どれを投稿しますか？ [y/n/select]」。選択されたものだけを投稿します。残りは会話に残します。 これは、投稿者が見る前にレビュアーが判断を下すということであり、 方向性に関する疑問を扱うのに適切なタイミングです。

重要な理由： 不適切な不変条件に関する判断は積み重なります。 誤った判断がいくつかあるだけで、コードベースは修復不能になります。 これは、ドキュメントを改善すれば解決できるコンテキストの問題ではなく、 人間の知恵を必要とする判断の問題です。

フェーズ 5：バックログのトリアージ

各 BACKLOG 項目について、検出されたプラットフォームにイシューを作成します：

# GitHub
gh issue create \
  --title "[Tech Debt] Brief description" \
  --body "## Context
Identified during PR #<number> review.
..." \
  --label "tech-debt"

# GitLab
glab issue create \
  --title "[Tech Debt] Brief description" \
  --description "## Context
Identified during MR !<number> review.
..." \
  --label "tech-debt"

確認： --help フラグを付けてコマンドを実行し、利用可能であることを確認してください。

作成前にユーザーに確認する：「バックログ項目が N 件見つかりました。イシューを作成しますか？ [y/n/select]」

フェーズ 6：レポートの生成

分類ごとにレポートを構成します。すべての BLOCKING および IN-SCOPE の指摘には、modules/educational-insights.md に従って 教育的な知見を含める必要があります。理由（原則）、 根拠（ベストプラクティスへのリンク）、学びのポイント （一般化した教訓）を記載します。SUGGESTION の指摘には理由を含め、 根拠は任意で記載します。BACKLOG 項目には簡潔な理由だけが必要です。

--concise を指定すると、これらの段落は投稿されません。差分の行に 紐づく指摘は、作成者が適用できるサジェスチョンブロックとなり、 明確化が必要な場合に限り、その横に短い説明が付きます。 アンカーにできる行がない指摘は、概要にそれぞれ1行で表示されます。 教育的な内容を含む完全なレポートは、--local で指定したパスに ローカル保存されるため、情報が失われることはありません。MR には 投稿されません。投稿パターンについては、modules/suggestion-comments.md を 参照してください。

## PR #X: Title

### Scope Compliance
**Requirements:** (from plan/spec)
1. [x] Requirement A - Implemented
2. [x] Requirement B - Implemented
3. [ ] Requirement C - **Missing**

### Blocking (1)
1. [B1] SQL injection via string concatenation
   - **Location**: `db/queries.py:89`
   - **Anchor**: `cursor.execute("SELECT * FROM t WHERE id = " + uid)`
   - **Issue**: User input interpolated directly into SQL
   - **Why**: String-interpolated SQL allows attackers to
     execute arbitrary queries (CWE-89). This is the #1
     web application vulnerability per OWASP Top 10.
   - **Proof**: [OWASP SQL Injection](https://owasp.org/www-community/attacks/SQL_Injection)
   - **Teachable Moment**: Always use parameterized queries
     or an ORM. This applies everywhere user input reaches
     a database, cache, or search engine query.
   - **Fix**: Use parameterized query:
     `cursor.execute("SELECT * FROM t WHERE id = ?", (uid,))`

### In-Scope (1)
1. [S1] Missing validation for edge case
   - **Location**: `api.py:45`
   - **Anchor**: `def handle_request(payload):`
   - **Issue**: Empty input not handled per requirement
   - **Why**: Defensive validation at API boundaries
     prevents cascading failures in downstream logic.
   - **Proof**: [Postel's Law](https://en.wikipedia.org/wiki/Robustness_principle)
   - **Teachable Moment**: Validate inputs at system
     boundaries (API handlers, CLI args, file parsers)
     but trust internal function contracts.

### Suggestions (1)
1. [G1] Consider extracting helper function
   - **Why**: The repeated pattern on lines 30-35 and
     72-77 violates DRY. Extracting it reduces future
     bug surface.
   - Author's discretion

### Backlog → GitHub Issues (3)
1. #142 - Refactor authentication module
2. #143 - Add caching layer
3. #144 - Update deprecated dependency

### Recommendation
**APPROVE WITH CHANGES**
Address B1 and S1 before merge.

ローカル出力（--local）

--local [path] を指定すると、API 経由で投稿する代わりに、 フェーズ 6 のレポートをローカルの .md ファイルに書き込みます。デフォルトのパス： .pr-review/pr-<number>-review.md。このファイルには、レビューの概要、 テスト計画、バックログ項目が1つのドキュメントにまとめられます。 課題の作成と PR の説明の更新はスキップされます。 ナレッジの蓄積（フェーズ 7）は引き続き実行されます。

フェーズ 7：ナレッジの蓄積

レポートの生成後、スコアが60以上の指摘は、プロジェクトのレビュー用 チャンバー（decisions/、patterns/、standards/、 lessons/）に記録され、レポートの「蓄積したナレッジ」セクションに 一覧表示されます。ワークフローの全容については、modules/knowledge-capture.md を 参照してください。

フェーズ 8：理解度確認ループ（--interactive）

オプトインです。レビュアーが --interactive を指定していない場合は、 このフェーズをスキップしてください。

差分を対象としたソクラテス式の対話ループです。各やり取りは pass、 partial、または fail として評価され、gauntlet の共有進捗ストアに記録されます。 確認結果がマージの推奨内容を変えることはありません。フェーズ 6 のレポートに 「理解度」セクションが追加されます。

完全なターン順序、スコアリング表、カテゴリの対応付け、記録仕様については、 modules/interactive-review.md を参照してください。

品質ゲート

次の場合、PR を承認する必要があります：

• 明示された要件がすべて実装されている
• BLOCKING の問題が残っていない
• IN-SCOPE の問題が解決済み、または認識されている
• BACKLOG 項目が GitHub の課題として追跡されている
• 新しいコードパスをテストでカバーしている
• 修正を取り消すとテストが失敗する（取り消しテスト）
• エージェントが生成したコードで、レビュー・整理されていないものが残っていない
• 作成者が、変更した各セクションの動作と失敗する可能性のある状況を説明できる （単に「テストが通る」だけではなく、理解度を確認する）

指摘が根拠に基づいていることの検証（pr-review:findings-verified）

.review/findings.json に指摘を書き込み、引用検証ツールを実行し （Skill(imbue:review-core) のステップ 5）、検証ツールが却下した指摘は削除するか、 UNVERIFIED とラベル付けします。

避けるべきアンチパターン

スコープの拡大、完璧主義、スタイルを理由にブロックすること、変更されていない コードのレビュー、以前のコードが悪かったことしか証明しないテスト、無関係な変更の 抱き合わせ、説明できないコードのマージです。それぞれの詳細と代わりに行うことについては、 modules/anti-patterns.md を参照してください。

他のツールとの連携

• /fix-pr：レビューで問題が見つかった後の修正に使用します
• /pr：レビュー前の PR の準備に使用します
• pensive:unified-review：実際のコード分析に使用します
• pensive:bug-review：必要に応じて、さらに詳しいバグ調査に使用します
• scribe:slop-detector：ドキュメントとコミットメッセージの品質分析に使用します
• scribe:doc-generator：PR の説明文を作成する際のガイドライン（不要な表現を排除）に使用します

不要な表現の検出との連携

PR の文章と変更されたドキュメントで、AI 生成に特徴的なパターンをどのように チェックするかについては、modules/slop-detection.md を 参照してください。

完了条件

• スコープのベースラインを確立し、レポートに記録する
• 変更されたすべてのファイルを対象範囲内、対象範囲外、または阻害要因に分類する
• 対象範囲外の各指摘に、追跡可能なイシュー番号を付与する
• レポートで、承認、コメント、変更を要求のいずれか1つを推奨する
• すべての BLOCKING および IN-SCOPE の指摘に Location（ファイル:行）と逐語的な Anchor を記載し、citation_verifier.py が終了コード 0 を返す。または、未検証の指摘を削除するか UNVERIFIED とラベル付けする
• --interactive の場合：阻害要因または高リスクの指摘を含むすべてのハンクを調査するか、レビュアーがセッションを終了する
• --interactive の場合：評価対象のやり取りをすべて .gauntlet/progress/<developer>.json に記録し、レポートに Comprehension セクションを含め、その行数を記録された調査の件数と一致させる
• --concise の場合：差分行に関するすべての指摘を提案ブロックとして投稿し、概要レビューを作成し、テスト計画のコメントや説明の更新は投稿しない
• --hold-insights の場合：方向性またはアーキテクチャに関するすべての指摘を投稿前にチャットで提示し、選択されたものだけを PR に反映する

関連モジュール

• スコープの分類 - 指摘のカテゴリ
• 粗雑な記述の検出 - PR の文章に対する AI パターンのチェック
• レビューのアンチパターン - レビューで避けるべきことと、代わりに行うべきこと
• 対話型の理解度確認ループ - ソクラテス式の調査を評価し、gauntlet の適応型セレクターに記録する
• GitHub PR コメントのパターン - インラインおよび概要 PR コメント用の gh api パターン
• 提案コメント - GitHub と GitLab でワンクリックの提案ブロックを作成する方法と、--concise の投稿ルール