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

发现	操作
存在未关闭的议题	链接到该议题，不要重复创建
存在未关闭的 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：发现议题

# 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. 扫描议题、标签和先前已合并的工作。
2. 按难度和范围对候选项分类。
3. 推荐风险最低、范围最小的入门贡献。

故障排除

问题	原因	解决方案
找不到贡献指南	仓库缺少标准文件	根据已合并 PR 的历史记录和维护者评论推断惯例
可选议题太多	工作范围未限定	按标签、组件路径和维护者近期活动筛选
建议的工作似乎有风险	存在隐藏依赖或影响范围过广	缩小到更具体的文件或领域边界，并重新说明假设
输出过于笼统	仓库证据不足	添加具体的文件/PR 引用，并明确指出模式

参考文档

• references/pr-research.feature — 可执行规范：探索上游惯例/结构、撰写附有引用的上游研究材料、作为计划前的第一步（soc-qk4b）

• references/upstream-research-checklist.md