pr-research

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PR Research Skill

PR Research 技能

Systematic exploration of upstream repositories before contributing.

在贡献前对上游代码库进行系统性探索。

Overview

概述

Research an external codebase to understand how to contribute effectively. This is the FIRST step before planning or implementing an open source contribution.

When to Use:

Before contributing to an external repository
Starting a new open source contribution
Evaluating whether to contribute to a project

When NOT to Use:

Researching your own codebase (use
```
$research
```
)
Already familiar with the project's guidelines

研究外部代码库，以了解如何高效地做出贡献。这是规划或实施开源贡献前的第一步。

适用场景：

向外部代码库贡献之前
开启新的开源贡献项目时
评估是否要为某个项目做贡献时

不适用场景：

研究自己的代码库（请使用
```
$research
```
）
已经熟悉项目的贡献指南时

Workflow

工作流

-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. 已有工作检查    -> 阻塞项：检查是否存在相关议题/PR
0.  CONTRIBUTING.md     -> 强制项：查找贡献指南
1.  代码库设置    -> 克隆/确定上游代码库
2.  指南分析 -> 模板、行为准则（CODE_OF_CONDUCT）
3.  PR 溯源分析      -> 分析已合并的PR、提交模式
4.  维护者研究 -> 回复模式、评审期望
5.  议题发现     -> 寻找贡献机会
6.  输出              -> 撰写研究文档

Phase -1: Prior Work Check (BLOCKING)

阶段-1：已有工作检查（阻塞项）

CRITICAL: Before ANY research, check if someone is already working on this.

bash

undefined

关键：在开展任何研究之前，先检查是否已经有人在处理相关工作。

bash

undefined

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

搜索可能解决该问题的公开PR

gh pr list -R <owner/repo> --state open --search "<topic keywords>" --limit 20

Check for recently merged PRs (might already be fixed)

检查最近合并的PR（问题可能已被修复）

gh pr list -R <owner/repo> --state merged --search "<topic keywords>" --limit 10


| Finding | Action |
|---------|--------|
| Open issue exists | Link to it, don't create duplicate |
| Open PR exists | Don't duplicate work |
| Recently merged PR | Verify fix, no work needed |
| No prior work found | Proceed to Phase 0 |

---

gh pr list -R <owner/repo> --state merged --search "<topic keywords>" --limit 10


| 发现结果 | 行动 |
|---------|--------|
| 存在公开议题 | 链接到该议题，不要创建重复议题 |
| 存在公开PR | 不要重复工作 |
| 最近有合并的PR | 验证修复情况，无需再开展工作 |
| 未发现已有工作 | 进入阶段0 |

---

Phase 0: CONTRIBUTING.md Discovery (BLOCKING)

阶段0：查找CONTRIBUTING.md（阻塞项）

CRITICAL: Do not proceed without finding contribution guidelines.

bash

undefined

关键：未找到贡献指南前不要继续。

bash

undefined

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

检查README中的贡献相关章节

grep -i "contribut" README.md | head -10

undefined

grep -i "contribut" README.md | head -10

undefined

Extract Key Requirements

提取核心要求

Requirement	Where to Find
Commit format	"Commit messages" section
PR process	"Pull Requests" section
Testing requirements	"Testing" section
Code style	"Style" section
CLA/DCO	"Legal" or "License" section

要求	查找位置
提交格式	"Commit messages"章节
PR流程	"Pull Requests"章节
测试要求	"Testing"章节
代码风格	"Style"章节
CLA/DCO	"Legal"或"License"章节

Phase 3: PR Archaeology

阶段3：PR溯源分析

CRITICAL: Understand what successful PRs look like.

bash

undefined

关键：了解成功PR的特征。

bash

undefined

List recent merged PRs

列出最近合并的PR

gh pr list --state merged --limit 20

Recent commit style

Check for conventional commits

检查是否使用约定式提交

undefined

undefined

PR Size Analysis

PR规模分析

Size	Files	Lines	Likelihood
Small	1-3	<100	High acceptance
Medium	4-10	100-500	Moderate
Large	10+	500+	Needs discussion first

规模	文件数	代码行数	接受可能性
小型	1-3	<100	高
中型	4-10	100-500	中等
大型	10+	500+	需先讨论

Phase 5: Issue Discovery

阶段5：议题发现

bash

undefined

bash

undefined

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

未分配负责人的议题

---

---

Output

输出

Write to

.agents/research/YYYY-MM-DD-pr-{repo-slug}.md

markdown

undefined

写入文件

.agents/research/YYYY-MM-DD-pr-{repo-slug}.md

markdown

undefined

PR Research: {repo-name}

Executive Summary

执行摘要

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

{2-3句话：项目健康状况、贡献友好度}

Contribution Guidelines

贡献指南

Document	Status	Key Requirements
CONTRIBUTING.md	Present/Missing	{summary}
PR Template	Present/Missing	{required sections}

文档	状态	核心要求
CONTRIBUTING.md	存在/缺失	{摘要}
PR模板	存在/缺失	{必填章节}

PR Patterns

PR模式

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

平均规模：X个文件，Y行代码
提交风格：{约定式/命令式等}
评审时间：约X天

Contribution Opportunities

贡献机会

Issue	Type	Difficulty
#N	bug/feat	easy/medium

议题	类型	难度
#N	bug/feat	简单/中等

Next Steps

下一步行动

$pr-plan .agents/research/YYYY-MM-DD-pr-{repo}.md

---

$pr-plan .agents/research/YYYY-MM-DD-pr-{repo}.md

---

Anti-Patterns

反模式

DON'T	DO INSTEAD
Skip guidelines check	Always read CONTRIBUTING.md first
Ignore PR patterns	Study successful merged PRs
Start with large PRs	Begin with small, focused changes

不要做	建议做法
跳过指南检查	务必先阅读CONTRIBUTING.md
忽略PR模式	研究已成功合并的PR
从大型PR开始	从小型、聚焦的修改入手

Workflow Integration

工作流集成

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

$pr-research <repo> -> $pr-plan <research> -> 实现 -> $pr-prep

Examples

示例

Research Upstream Before Contributing

贡献前研究上游代码库

User says: "Do PR research for

owner/repo

before I propose a fix."

What happens:

Inspect contribution guidelines and governance files.
Analyze merged PR patterns and conventions.
Produce a research artifact with opportunities and risks.

用户指令：“在我提出修复方案前，为

owner/repo

做PR研究。”

执行流程：

检查贡献指南和治理文件。
分析已合并PR的模式和约定。
生成包含贡献机会与风险的研究文档。

Scope Discovery

范围探索

User says: "Find small starter contribution options in this repo."

What happens:

Scan issues/labels and prior merged work.
Classify candidates by difficulty and scope.
Recommend a smallest-safe starting contribution.

用户指令：“在这个代码库中寻找适合新手的小型贡献任务。”

执行流程：

扫描议题/标签以及已合并的历史工作。
按难度和范围对候选任务进行分类。
推荐最适合入门的小型安全贡献任务。

Troubleshooting

故障排查

Problem	Cause	Solution
No contribution guide found	Repo lacks standard files	Infer conventions from merged PR history and maintainers' comments
Too many possible issues	Scope not constrained	Filter by labels, component paths, and recent maintainer activity
Suggested work seems risky	Hidden dependency or broad blast radius	Downscope to narrower file/domain boundary and restate assumptions
Output is too generic	Insufficient repository evidence	Add concrete file/PR references and explicit pattern findings

问题	原因	解决方案
未找到贡献指南	代码库缺少标准文件	从已合并的PR历史和维护者评论中推断约定
可选议题过多	范围未限定	按标签、组件路径和维护者近期活动进行筛选
建议的工作存在风险	存在隐藏依赖或影响范围过广	将范围缩小到更具体的文件/领域边界，并重新说明假设
输出内容过于通用	代码库相关证据不足	添加具体的文件/PR引用以及明确的模式发现结果

pr-research

Original

Translation

PR Research Skill

PR Research 技能

Overview

概述

Workflow

工作流

Phase -1: Prior Work Check (BLOCKING)

阶段-1：已有工作检查（阻塞项）

Search for open issues on this topic

搜索该主题的公开议题

Search for open PRs that might address this

搜索可能解决该问题的公开PR

Check for recently merged PRs (might already be fixed)

检查最近合并的PR（问题可能已被修复）

Phase 0: CONTRIBUTING.md Discovery (BLOCKING)

阶段0：查找CONTRIBUTING.md（阻塞项）

Check all common locations

检查所有常见位置

Check README for contribution section

检查README中的贡献相关章节

Extract Key Requirements

提取核心要求

Phase 3: PR Archaeology

阶段3：PR溯源分析

List recent merged PRs

列出最近合并的PR

Recent commit style

最近的提交风格

Check for conventional commits

检查是否使用约定式提交

PR Size Analysis

PR规模分析

Phase 5: Issue Discovery

阶段5：议题发现

Find beginner-friendly issues

查找适合初学者的议题

Issues with no assignee

未分配负责人的议题

Output

输出

PR Research: {repo-name}

PR Research: {repo-name}

Executive Summary

执行摘要

Contribution Guidelines

贡献指南

PR Patterns

PR模式

Contribution Opportunities

贡献机会

Next Steps

下一步行动

Anti-Patterns

反模式

Workflow Integration

工作流集成

Examples

示例

Research Upstream Before Contributing

贡献前研究上游代码库

Scope Discovery

范围探索

Troubleshooting

故障排查