qa-pr-requirements-analyzer

QA PR 需求分析器

审查 PR 中由人工编写的上下文——标题、描述、评论、关联工单、附加图片——以提取原始需求、验证范围，并生成下游技能（qa-write-test-cases）可使用的需求摘要。

与 pull-request-diff-analyzer 互补：

技能	输入	输出	重点
pull-request-diff-analyzer	git diff、变更文件	从代码变更中提取 AC	“代码的实际行为”
qa-pr-requirements-analyzer	PR 标题、描述、评论、关联问题	包含范围验证和 AC 的需求摘要	“PR 应该实现什么”

• 一起使用可全面了解情况。
• 如果用户只想了解代码改动，请改用 pull-request-diff-analyzer。

第 1 步：检测 PR 上下文

按以下优先级接受：

1. 用户提示中提供的 PR 编号或 URL（例如 https://github.com/org/repo/pull/1234）。
2. 当前分支对应的开放 PR：gh pr view --json number,title,baseRefName,headRefName,url。
3. 仅提供工单键（Jira PRJ-123、Linear 等）——分析工单，然后检查是否有引用该工单的开放 PR。

• 如果无法检测到任何信息，请向用户索取 PR 编号/URL、分支名称或工单键。
• 如果分支仅存在于本地，请让用户推送该分支，或直接提供 PR 详情。

第 2 步：读取 PR 上下文

收集开发者和团队编写的内容——而非代码。检测可用的 MCP/CLI 工具并获取：

• PR 元数据（标题、描述、评论、标签、里程碑、负责人）——如果启用 Jira/Linear/GitHub MCP，则通过相应 MCP 获取；否则使用 gh CLI。
• 正文中的嵌入图片/图表——读取它们（使用具备视觉能力的 Agent，或使用 fetch 获取并描述）；它们往往展示文字未提及的 UI 变更、错误状态或流程。
• 关联工单——解析 PR 正文和分支名称，查找工单引用。

不得捏造工单内容或添加错误信息。

第 3 步：解析关联工单

PR 描述通常只是简略摘要；工单才包含实际需求。使用最先可用的工具：

1. 如果启用了 Jira/Linear MCP，则使用它获取问题摘要、描述、AC、评论、关联问题和附件。
2. 如果启用了 GitHub MCP，则使用它获取关联问题。
3. 使用 gh CLI 作为后备方案——gh issue view {N} --json title,body,comments,labels。对于未启用 MCP 的 Jira/Linear，请让用户粘贴问题内容。
4. 如果无法访问，请在输出中明确说明这一缺口，并根据现有信息继续处理。

第 4 步：验证范围并发现歧义

比较 PR 的内容与工单的要求。以下是需要提出的问题，而不是断言代码有问题。

范围验证 — 列出三项：

• 范围内 — PR 已处理的工单要求（查看描述或代码，参见第 5 步）。
• 范围外 — 工单中没有对应 PR 改动的要求。这是此技能最有价值的输出。
• 额外内容（工单未提及）— PR 中未在工单中提及的改动。标记出来以供审核（是有意还是意外改动？）。

歧义、边界情况、开放问题 — 仅提出有现有上下文支持的问题。不要臆造新要求，也不要假定产品应处理某种情况，除非工单、PR 描述、评论或周边上下文表明此情况相关。请留意：

• 未充分说明的行为 — 工单描述了一项功能，但遗漏了重要细节（例如，要求导出，却未定义格式、命名、权限或空状态行为）。
• 未答复的评论 — PR 或工单评论中的问题尚无明显答复。
• 相互冲突的要求 — 工单、评论或 PR 描述的不同部分存在分歧。
• 可能相关的边界情况 — 与已声明要求相关，但预期行为未明确的场景。请将其作为问题提出，而不是要求。
  • 绝不要仅仅因为某种边界情况是常见的软件问题就报告它。
  • 只有当工单、PR 描述、受影响领域或讨论表明某种边界情况可能相关时，才提出。

第 5 步：确定受影响的文件

不要深入审查代码 — 这属于 pull-request-diff-analyzer 的工作。优先查看 PR 描述或工单中提及的文件；只有当描述没有列出文件时，才使用 git diff {base}...HEAD --name-only 交叉核对。

短路处理（未改变源代码行为）： 如果所有改动文件都不是源代码（*.md、docs/**、tests/**、配置、CI、依赖项、锁文件）：

• 不要臆造验收标准。不要调用 pull-request-diff-analyzer。
• 生成简短摘要：PR 标题、类型（docs/chore/ci/deps）、一句话说明 Changes、完整文件列表。
• 添加注释 > No source code behavior changed. Acceptance criteria generation is not applicable for this PR.
• 到此为止。

PR 描述为空： 如果没有正文，且分支名未表明意图：

• 获取 git log {base}..HEAD --pretty=format:"%s%n%b"。
• 结合改动文件和分支名，写出一句暂定的 Changes。
• 标记 > PR description was empty. Summary derived from branch name, commits, and changed files only.
• 如果存在关联工单，应优先以工单为准，并在“歧义”部分注明 PR 正文为空。

第 6 步：生成需求摘要

仅当原始提示明确要求保存时，才保存为 .md 文件。 将文件写入用户指定的文件夹。

文件名：将 PR 标题转换为 slug（小写、用连字符分隔、不含特殊字符，最多 40 个字符），并附加 PR 编号。例如：Add user export to CSV → add-user-export-to-csv-pr-1234.md。

输出模板（已填写示例：summary-example.md）：

## PR Requirements Summary

**PR:** {title}
**Branch:** {headRefName} → {baseRefName}
**Type:** {feature | bugfix | refactor | deps}
**Linked Tickets:** ... (only if any exist)

**Source of Truth:**
- PR description: {present | empty — derived from commits/branch}
- Jira/GitHub ticket: {resolved | not resolved — no MCP available}
- Most reliable source: {PR description | ticket | commits}

**Changes Overview:** ... (1-2 sentences — intent, not implementation)

**Impacted Areas:**
- Payment processing (6 source files)
- Billing configuration (2 config files)
- ... (bullet list, only meaningful business/technical impact; omit if empty)

**High Level Key files (up to 5):**
- `path/to/file.ts` — source
- ... (categorized: source | config | test | docs | migration | deps)

**Scope Verification:**
- ✅ In scope: {ticket requirement → where in PR it is addressed}
- ⚠️ Out of scope: {ticket requirement not addressed in PR}
- ➕ Extra (not in ticket): {change present in PR but not in ticket}

**Ambiguities, Edge Cases & Open Questions:**
- ... (underspecified behavior / unanswered comment / conflicting requirement / missing edge case)
- ... (empty input / permissions / error path / performance / backward compatibility / ...)
- ...

**Acceptance Criteria:**
- {action to perform} → {expected result}
- ...

摘要规则：

• 简洁、概括层面的需求，不涉及实现 — 这是需求文档，不是代码审查。
• Changes Overview 用 1-2 句话概述。
• Impacted Areas — 列出有意义的项目；如果为空则省略此部分。
• 必须包含 Source of Truth — 告知下游技能在信息来源不一致时应以何者为准。
• Acceptance Criteria — 可测试、面向用户，并采用“操作 → 预期结果”的表述。如果未改变源代码行为，则用第 5 步明确的“不适用”注释替换此部分。
• 省略空部分，不要填写 None/N/A — 但“未更改源代码”注释必须明确写出。
• 避免使用“代码清理”“小幅修复”“各种改进”等泛泛表述 — 明确说明改动内容，否则省略。

参考资料

描述	文件
已填写的输出摘要示例	summary-example.md
.testeiya/ 目录约定	../scan-automation-project/SKILL.md
聚焦代码的 PR 分析（配套技能）	../pull-request-diff-analyzer/SKILL.md
下游：根据需求生成测试用例	../qa-write-test-cases/SKILL.md
下游：将生成的用例同步到 Testomat.io	../sync-test-cases-with-tms/SKILL.md