github-pr-review

Files (11)

• README.md
• README_ja.md
• SKILL.md
• openai.yaml · agents/
• findings.md · references/
• dismiss_my_reviews.sh · scripts/
• fetch_prior_findings.sh · scripts/
• post_review.sh · scripts/
• render_review.py · scripts/
• resolve_review_range.sh · scripts/
• resolve_review_threads.sh · scripts/

SKILL.md (first lines)

# Pull Request Review

PRのhead commitをworktreeにチェックアウトし、重点の異なる2つのFinder SubAgentが指摘候補を探す。
Finder SubAgentが出した指摘候補は、1件ずつVerifier SubAgentが反証を試み、
検証を通過したものだけを要修正事項としてレビューレポートとinline commentに投稿する。
spec sourceを解決できる場合は、Contract SubAgentがspecとの不整合の指摘候補を第2の軸として探し、同じくVerifierの検証を経たものだけをレビューに含める。

## Arguments

- `PR number`: レビューするPR番号 (optional, defaults to PR for current branch)
- `--spec <issue-number>`: Contract reviewに使うspecのGitHub Issue番号。指定時は関連Issueより優先する
- `--dry-run`: 生成したレポート本文をチャットに提示するのみで、`post_review.sh` 等の投稿スクリプト・dismiss・resolve操作を一切呼ばない(worktreeの後片付けは通常どおり行う)

## Task

1回の実行で扱うPRは1件だけとする。複数のPRのレビューを依頼された場合は、同じcontextで並行させず、1件のPhase 4が終わってから次のPRを始める。並行させると、別のPRのdiffやcontractが入力に混ざる。

### Phase 1: 準備

#### Phase 1.1: 対象PRの特定

- **引数にPR番号が指定されている場合**: 指定されたPRを対象にする
- **引数なし**
  - **現在のブランチに紐づくopen PRが存在する場合**: そのPRをそのまま使用する(確認なし)
  - **現在のブランチに紐づくopen PRが存在しない場合**: RemoteのOpen PR一覧を取得し、`AskUserQuestion`でユーザーに対象PRを確認する。Open PRが1件もなければその旨を報告して終了する

#### Phase 1.2: PR情報とGitHub上の状態の収集

以下を取得する。

- PR情報: repository名、タイトル、本文、base・head branch、最新head commit SHA
- CI: checkの結果、失敗したcheckの名前・URL・取得可能な関連ログ
- 自分の既存レビュー: 以前に投稿した指摘と返信、`APPROVED` / `CHANGES_REQUESTED` レビューID

最新head commit SHAは `<latest-commit-sha>` として保持する。
CIの失敗はレポートの概要に記載し、Finderの内部証拠として使用する。
以前に投稿した指摘は、resolve済みのthreadも含めて返信とともに取得する。返信には、各指摘を修正したか、見送ったか、却下したかが記録されている。再レビューのたびに以前のthreadはresolveされるため (Phase 3.3)、未resolveのthreadだけを見ると前々回以前の判断が抜け落ち、決着済みの指摘を蒸し返すことになる。

```bash
bash "<skill-dir>/scripts/fetch_prior_findings.sh" --repo "<owner/repo>" --pr "<number>"
```

出力はPhase 1.3で `<review-temp-dir>/prior-findings.json` に書き出す。このうち `is_resolved` がfalseのthread IDを `<existing-thread-ids>`、レビューIDを `<existing-review-ids>` として保持する。

さらに、Contract review用のspec contractを次の順で解決する。

1. `--spec` が指定されていれば、そのIssueを使う
2. PR本文に `Closes #N` があれば、Issue #Nを使う

Issueは `gh issue view <N> --json title,body,comments` で取得し、次をこの順に並べてspec contractとする。

- 本文のcontractセクション群 (Context〜Out of Scope、Decision Log)。contractセクション群を持たない普通のIssueでは本文全体
- `authorAssociation` が `OWNER` / `MEMBER` / `COLLABORATOR` のコメント。投稿日時と投稿者を付け、古い順に並べる。本文の後に合意した判断やscopeの変更は、ここに記録されていることが多い

明文に無い期待を検査しない原則は変わらないため、記述の薄いIssueではContract指摘は自然に少なくなる。

どちらでも解決できない場合はContract軸をスキップする。スキップしたことはレポート本文にもinline commentにも書かず、Phase 4のチャット報告にだけ含める。解決したspec contractは、Phase 1.3で `<review-temp-dir>/spec-contract.md` に書き出す。

他のレビュワーのレビューやthreadは参照しない。初回レビューではどちらのID一覧も空になる。

#### Phase 1.3: worktreeとレビュー環境の準備

1. `<repo-root>/.tmp/<repo-name>-worktrees/pr-<number>-review` を専用worktree pathとする。
2. 同じpathのworktreeが存在し、未commit変更がある場合は中止する。cleanな場合のみ作り直してよい。
3. PRの最新head commitとbase branchを取得し、head commitをdetached状態で専用worktreeにcheckoutする。
4. 専用worktreeをレビュー対象のsnapshotとし、Phase 2以降では対象ファイルをすべてこのsnapshot内から参照する。
5. レビュー実行ごとに `mktemp -d` で一意な `<review-temp-dir>` を作成する。SubAgentへの大きな入力は、promptに埋め込まずこのdirectoryのファイルで渡す。
6. レビュー範囲を決め、diff、変更ファイル一覧、変更履歴を `<review-temp-dir>` に書き出す。

   ```bash
   bash "<skill-dir>/scripts/resolve_review_range.sh" \
     --repo "<owner/repo>" --pr "<number>" \
     --base-ref "<fetched-base-ref>" --head "<latest-commit-sha>" \
     --out-dir "<review-temp-dir>"
   ```

   標準出力のJSONの `baseline` を `<baseline-sha>` として保持する。baselineはbase branchとのmerge-baseで、base branchに後から入った変更をdiffに含めない。PRのcommitに未mergeの別のopen PRのheadが含まれる積み上げPRでは、そのheadがbaselineになる。このとき `dependencyPr` のPRの変更はレビュー対象外とし、その旨を `<pr-title-and-body>` の末尾に1行追記してSubAgentへ伝える。

7. spec contractを解決できた場合は `<review-temp-dir>/spec-contract.md` に書き出す。
8. Phase 1.2で取得した以前の指摘を `<review-temp-dir>/prior-findings.json` に書き出す。

### Phase 2: レビュー

#### Phase 2.1: FinderとContract SubAgentの実行

`code-reviewer-finder` を2つ並列に起動する。`<spec-contract>` を解決できた場合は `code-reviewer-contract` も並列に起動する。
Finderはmergeを止める問題の指摘候補を、Contractはspec contractとの食い違い (未充足・boundary違反・scope creep) の指摘候補を収集する。specとコードのどちらが正しいかは判定せず、どちらかを直して一致させることを完了条件にする。
レビュー方法、実行制約、出力形式はそれぞれのagent定義に従う。
次のprompt templateを使用する。

```text
以下の対象変更を、agent定義の責務・判定基準・出力形式に従ってレビューする。
あなたの役割: <role>
重点視点: <focus>

重点視点に限定せず、対象変更の全変更単位を確認する。

対象変更:
- 対象種別: GitHub PR
- PR番号: <pr-number>
- 変更目的・説明: <pr-title-and-body>
- 変更ファイル一覧: <review-temp-dir>/changed-files.txt
- diff: <review-temp-dir>/diff.patch
- 変更履歴: <review-temp-dir>/commits.txt
- 変更サマリ: <change-summary>
- snapshotの絶対パス: <snapshot-path>
- baseline識別子: <baseline-sha>
- snapshot識別子: <head-sha>
- 追加証拠: <ci-evidence>
- 以前の指摘と対応: <review-temp-dir>/prior-findings.json
- spec contract: <spec-contract>

ファイルで渡した入力は、レビューを始める前に全文を読む。
```

`<role>` と `<focus>` は次の組み合わせを使用する。

- Finder 1: `Finder` / 期待される振る舞い、契約、不変条件、呼び出し経路、状態・データの流れ、同時に更新すべきdiff外の箇所
- Finder 2: `Finder` / 境界値、失敗、並行実行、互換性、信頼できない入力、回復不能な状態

From mjun0812/skills, MIT.

More from mjun0812/skills