用途
pr-research 用于在向外部开源仓库贡献代码前，系统性地研究上游代码库，理解如何有效参与贡献。这是规划或实现开源贡献之前的第一个步骤。
适用场景：
- 向外部仓库贡献之前
- 开始新的开源贡献
- 评估是否值得向某个项目贡献
不适用场景：
- 研究自己的代码库（可使用 $research）
- 已经熟悉该项目指南
工作流程
流程包含以下阶段：
-1. 先前工作检查（阻塞）— 检查是否已有相关议题或 PR 0. CONTRIBUTING.md（强制）— 查找贡献指南
- 仓库准备 — 克隆/识别上游仓库
- 指南分析 — 模板、CODE_OF_CONDUCT
- PR 考古 — 分析已合并 PR、提交模式
- 维护者研究 — 响应模式、评审期望
- 议题发现 — 寻找贡献机会
- 输出 — 撰写研究文档
阶段 -1：先前工作检查（阻塞）
在任何研究之前，先检查是否已有人在做这件事。使用 gh 命令搜索开放议题、开放 PR 和近期已合并 PR：
# 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 研究。” 发生的事：
- 检查贡献指南和治理文件。
- 分析已合并 PR 的模式和惯例。
- 产出一份包含机会和风险的研究产物。
示例二：范围发现 用户说：“在这个仓库里找一些小型入门贡献选项。” 发生的事：
- 扫描议题/标签和先前已合并的工作。
- 按难度和范围对候选进行分类。
- 推荐最小的安全起始贡献。
故障排除
- 未找到贡献指南：仓库缺少标准文件，从已合并 PR 历史和维护者评论中推断惯例。
- 可能有太多议题：范围未约束，按标签、组件路径和近期维护者活动过滤。
- 建议的工作似乎有风险：存在隐藏依赖或影响范围广，缩小到更窄的文件/领域边界并重述假设。
- 输出过于通用：仓库证据不足，添加具体的文件/PR 引用和明确的模式发现。
参考文档
- references/pr-research.feature — 可执行规范：探索上游惯例/结构，撰写带引用的上游产物，先于规划的第一步（soc-qk4b）
- references/upstream-research-checklist.md
限制
现有资料未提供关于收费、价格、平台兼容性或效果保证的信息。该技能的具体运行环境要求、依赖版本等暂未提供。