pr-research

PR リサーチスキル

コントリビューションを始める前に、上流リポジトリを体系的に調査します。

概要

外部のコードベースを調査して、効果的なコントリビューションの方法を理解します。 オープンソースへのコントリビューションを計画または実装する前に行う最初のステップです。

使用する場面：

• 外部リポジトリにコントリビューションする前
• 新しいオープンソースへのコントリビューションを始めるとき
• プロジェクトへのコントリビューションを検討するとき

使用しない場面：

• 自分のコードベースを調査するとき（$research を使用）
• プロジェクトのガイドラインをすでに把握しているとき

---

ワークフロー

-1. Prior Work Check    -> BLOCKING: Check for existing issues/PRs
0.  CONTRIBUTING.md     -> MANDATORY: Find contribution guidelines
1.  Repository Setup    -> Clone/identify upstream repo
2.  Guidelines Analysis -> Templates, CODE_OF_CONDUCT
3.  PR Archaeology      -> Analyze merged PRs, commit patterns
4.  Maintainer Research -> Response patterns, review expectations
5.  Issue Discovery     -> Find contribution opportunities
6.  Output              -> Write research document

---

フェーズ -1：過去の作業の確認（必須）

重要：調査を始める前に、すでに誰かが取り組んでいないか確認してください。

# Search for open issues on this topic
gh issue list -R <owner/repo> --state open --search "<topic keywords>" --limit 20

# Search for open PRs that might address this
gh pr list -R <owner/repo> --state open --search "<topic keywords>" --limit 20

# Check for recently merged PRs (might already be fixed)
gh pr list -R <owner/repo> --state merged --search "<topic keywords>" --limit 10

確認結果	対応
オープンな Issue がある	その Issue にリンクし、重複して作成しない
オープンな PR がある	作業を重複させない
最近マージされた PR がある	修正を確認し、作業が不要か判断する
過去の作業が見つからない	フェーズ 0 に進む

---

フェーズ 0：CONTRIBUTING.md の確認（必須）

重要：コントリビューションガイドラインを見つけるまでは先に進まないでください。

# Check all common locations
cat CONTRIBUTING.md 2>/dev/null
cat .github/CONTRIBUTING.md 2>/dev/null
cat docs/CONTRIBUTING.md 2>/dev/null

# Check README for contribution section
grep -i "contribut" README.md | head -10

主な要件の抽出

要件	確認場所
コミット形式	「Commit messages」セクション
PR の手順	「Pull Requests」セクション
テスト要件	「Testing」セクション
コードスタイル	「Style」セクション
CLA/DCO	「Legal」または「License」セクション

---

フェーズ 3：PR の調査

重要：成功した PR の特徴を把握してください。

# List recent merged PRs
gh pr list --state merged --limit 20

# Recent commit style
git log --oneline -30 | head -20

# Check for conventional commits
git log --oneline -30 | grep -E "^[a-f0-9]+ (feat|fix|docs|refactor|test|chore)(\(.*\))?:"

PR の規模分析

規模	ファイル数	行数	採用の可能性
小規模	1～3	<100	高い
中規模	4～10	100～500	中程度
大規模	10+	500+	まず相談が必要

---

フェーズ 5：Issue の確認

# Find beginner-friendly issues
gh issue list --label "good first issue" --state open
gh issue list --label "help wanted" --state open

# Issues with no assignee
gh issue list --state open --json assignees,title,number | \
  jq -r '.[] | select(.assignees | length == 0) | "#\(.number): \(.title)"' | head -10

---

出力

.agents/research/YYYY-MM-DD-pr-{repo-slug}.md に書き込みます。

# PR Research: {repo-name}

## Executive Summary
{2-3 sentences: project health, contribution friendliness}

## Contribution Guidelines
| Document | Status | Key Requirements |
|----------|--------|------------------|
| CONTRIBUTING.md | Present/Missing | {summary} |
| PR Template | Present/Missing | {required sections} |

## PR Patterns
- **Average size**: X files, Y lines
- **Commit style**: {conventional/imperative/etc}
- **Review time**: ~X days

## Contribution Opportunities
| Issue | Type | Difficulty |
|-------|------|------------|
| #N | bug/feat | easy/medium |

## Next Steps
-> `$plan .agents/research/YYYY-MM-DD-pr-{repo}.md`

---

避けるべきパターン

しないこと	代わりにすること
ガイドラインの確認を省略する	必ず最初に CONTRIBUTING.md を読む
PR のパターンを無視する	成功してマージされた PR を調べる
大規模な PR から始める	小規模で焦点を絞った変更から始める

---

ワークフローとの連携

$pr-research <repo> -> $plan <research> -> implement -> $pr-prep

例

コントリビューション前に上流を調査する

ユーザーの指示：「修正案を提案する前に、owner/repo の PR リサーチをしてください。」

実行内容：

1. コントリビューションガイドラインとガバナンス関連ファイルを確認します。
2. マージされた PR のパターンと慣例を分析します。
3. 機会とリスクをまとめた調査資料を作成します。

対象範囲の確認

ユーザーの指示：「このリポジトリで、初めてのコントリビューションに適した小規模な候補を見つけてください。」

実行内容：

1. Issue、ラベル、過去のマージ済み作業を調べます。
2. 難易度と対象範囲に基づいて候補を分類します。
3. リスクが最も低い小規模なコントリビューションを提案します。

トラブルシューティング

問題	原因	解決策
コントリビューションガイドが見つからない	リポジトリに標準ファイルがない	マージ済み PR の履歴とメンテナーのコメントから慣例を推測する
対象となる Issue が多すぎる	対象範囲が定まっていない	ラベル、コンポーネントのパス、最近のメンテナーの活動で絞り込む
提案された作業にリスクがありそう	隠れた依存関係、または影響範囲が広い	対象をより狭いファイルやドメインの境界に絞り、前提条件を明示する
出力が一般論に偏っている	リポジトリの根拠が不十分	具体的なファイルや PR を参照し、見つかったパターンを明記する

参考資料

• references/pr-research.feature — 実行可能な仕様：上流の慣例や構造を調査し、出典を示した上流調査資料を作成する。計画前の最初のステップ（soc-qk4b）

• references/upstream-research-checklist.md