Back to Details

arinhub-verify-requirements-coverage

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Verify Requirements Coverage

验证需求覆盖情况

Verify that a pull request or local changes fully implement the requirements described in a GitHub issue. Extracts the issue reference, analyzes the diff against the issue description, and produces a coverage report.
验证拉取请求（PR）或本地变更是否完全实现了GitHub Issue中描述的需求。提取Issue引用，对比代码差异与Issue描述，生成需求覆盖报告。

Input

输入

  • PR number or URL (optional): The pull request identifier. Accepts:
    • Number: 
      123
    • Hash-prefixed: 
      #123
    • Full URL: 
      https://github.com/owner/repo/pull/123
    • If omitted, verifies local changes instead.
  • Issue number (optional, local mode): When verifying local changes, an issue number can be provided to check coverage against (e.g., 
    issue #42
    ).
  • Diff file path (optional): Path to a pre-existing diff file (e.g., passed by 
    arinhub-code-reviewer
    ). If provided, skip fetching the diff in Step 7 and read this file instead.
  • PR编号或URL（可选）：拉取请求的标识符。支持以下格式：
    • 纯编号：
      123
    • 井号前缀：
      #123
    • 完整URL：
      https://github.com/owner/repo/pull/123
    • 若未提供，则验证本地变更。
  • Issue编号（可选，本地模式）：验证本地变更时，可指定Issue编号以检查需求覆盖情况（例如：
    issue #42
    ）。
  • 差异文件路径（可选）：预先生成的diff文件路径（例如由
    arinhub-code-reviewer
    传递）。若提供此路径，则跳过步骤7的diff获取操作，直接读取该文件。

Procedure

操作流程

1. Determine Review Target

1. 确定审查目标

  • Remote PR: If the user provides a PR number or URL (e.g., "Verify PR #123"), target that remote PR. Set 
    MODE=remote
    .
  • Local Changes: If no specific PR is mentioned, or if the user asks to "verify my changes" or "do my changes cover the issue", target the current local changes (staged and unstaged). Set 
    MODE=local
    .
  • 远程PR：若用户提供了PR编号或URL（例如：「验证PR #123」），则以该远程PR为目标。设置
    MODE=remote
    。
  • 本地变更：若未指定具体PR，或用户要求「验证我的变更」「我的变更是否覆盖Issue需求」，则以当前本地变更（已暂存和未暂存的内容）为目标。设置
    MODE=local
    。

2. Resolve Identifier

2. 解析标识符

If 
MODE=remote
:
Extract the PR number from the user input. Strip any 
#
prefix or parse the number from a URL.
PR_NUMBER=<extracted number>
If 
MODE=local
:
Determine the current branch name for identification.
BRANCH_NAME=$(git branch --show-current | tr '/' '-')
若
MODE=remote
：
从用户输入中提取PR编号，去除
#
前缀或从URL中解析编号。
PR_NUMBER=<提取的编号>
若
MODE=local
：
获取当前分支名称用于标识。
BRANCH_NAME=$(git branch --show-current | tr '/' '-')

3. Fetch Metadata

3. 获取元数据

If 
MODE=remote
:
Gather PR details including body and linked issues:
bash
gh pr view $PR_NUMBER --json number,title,body,baseRefName,headRefName,files,url
If 
MODE=local
:
Gather local change details (staged and unstaged combined):
bash
git diff --name-only HEAD
若
MODE=remote
：
收集PR的详细信息，包括描述内容和关联的Issue：
bash
gh pr view $PR_NUMBER --json number,title,body,baseRefName,headRefName,files,url
若
MODE=local
：
收集本地变更的详细信息（已暂存和未暂存内容的合并结果）：
bash
git diff --name-only HEAD

4. Extract Linked Issue Number

4. 提取关联Issue编号

If 
MODE=remote
:
Determine the related issue using these methods in priority order:
Method A -- Closing keywords in PR body:
Search the PR body for GitHub closing keywords followed by an issue reference:
  • closes #N
    , 
    fixes #N
    , 
    resolves #N
    (and their variants: 
    close
    , 
    closed
    , 
    fix
    , 
    fixed
    , 
    resolve
    , 
    resolved
    )
  • Full URL references: 
    closes https://github.com/owner/repo/issues/N
Method B -- GitHub linked issues API:
bash
gh api graphql \
  -F owner='{owner}' \
  -F repo='{repo}' \
  -F pr_number=$PR_NUMBER \
  -f query='
    query($owner: String!, $repo: String!, $pr_number: Int!) {
      repository(owner: $owner, name: $repo) {
        pullRequest(number: $pr_number) {
          closingIssuesReferences(first: 10) {
            nodes { number title }
          }
        }
      }
    }
  ' --jq '.data.repository.pullRequest.closingIssuesReferences.nodes'
Method C -- Issue reference in PR body:
If Methods A and B yield no results, scan the PR body for any 
#N
pattern or issue URL that is not a closing keyword reference.
If 
MODE=local
:
Determine the related issue using these methods in priority order:
Method A -- User-provided issue number: If the user explicitly provided an issue number (e.g., "verify my changes against issue #42"), use that directly.
Method B -- Branch name convention: Extract an issue number from the branch name if it follows a convention like 
feature/42-description
, 
fix/42
, 
issue-42-description
, 
42-description
, 
jj/42-description
, etc.
No issue found: If no linked issue can be determined, inform the user and stop. Do not guess or fabricate an issue number.
ISSUE_NUMBER=<extracted number>
If multiple issues are found, process each one and produce a separate coverage report per issue.
若
MODE=remote
：
按以下优先级顺序确定关联的Issue：
方法A -- PR描述中的关闭关键字：
在PR描述中搜索GitHub关闭关键字及对应的Issue引用：
  • closes #N
    、
    fixes #N
    、
    resolves #N
    （及其变体：
    close
    、
    closed
    、
    fix
    、
    fixed
    、
    resolve
    、
    resolved
    ）
  • 完整URL引用：
    closes https://github.com/owner/repo/issues/N
方法B -- GitHub关联Issue API：
bash
gh api graphql \
  -F owner='{owner}' \
  -F repo='{repo}' \
  -F pr_number=$PR_NUMBER \
  -f query='
    query($owner: String!, $repo: String!, $pr_number: Int!) {
      repository(owner: $owner, name: $repo) {
        pullRequest(number: $pr_number) {
          closingIssuesReferences(first: 10) {
            nodes { number title }
          }
        }
      }
    }
  ' --jq '.data.repository.pullRequest.closingIssuesReferences.nodes'
方法C -- PR描述中的Issue引用：
若方法A和B未找到结果，则扫描PR描述中所有非关闭关键字的
#N
格式或Issue URL。
若
MODE=local
：
按以下优先级顺序确定关联的Issue：
**方法A -- 用户提供的Issue编号：**若用户明确指定了Issue编号（例如：「验证我的变更是否符合Issue #42的要求」），则直接使用该编号。
**方法B -- 分支名称约定：**若分支名称遵循
feature/42-description
、
fix/42
、
issue-42-description
、
42-description
、
jj/42-description
等约定，则从中提取Issue编号。
**未找到Issue：**若无法确定关联的Issue，需告知用户并终止操作，不得猜测或伪造Issue编号。
ISSUE_NUMBER=<提取的编号>
若找到多个Issue，需分别处理每个Issue并生成独立的需求覆盖报告。

5. Fetch Issue Details

5. 获取Issue详情

Retrieve the full issue description:
bash
gh issue view $ISSUE_NUMBER --json number,title,body,labels
获取完整的Issue描述：
bash
gh issue view $ISSUE_NUMBER --json number,title,body,labels

6. Extract Requirements from Issue

6. 从Issue中提取需求

Parse the issue body and title to identify discrete, testable requirements. Look for:
  • Checklist items (
    - [ ]
    or 
    - [x]
    )
  • Numbered steps or acceptance criteria
  • Explicit behavioral descriptions ("should", "must", "when X then Y")
  • UI changes, API changes, or data model changes mentioned
  • Edge cases or error handling requirements
  • Non-functional requirements (performance, security, accessibility)
Produce a numbered list of requirements:
R1: <requirement description>
R2: <requirement description>
...
If the issue body is vague or contains no clear requirements, use the issue title and any available context to infer the expected behavior. Flag inferred requirements clearly.
解析Issue的标题和描述内容，识别可独立测试的需求。重点关注：
  • checklist项（
    - [ ]
    或 
    - [x]
    ）
  • 编号步骤或验收标准
  • 明确的行为描述（包含「应该」「必须」「当X发生时则Y」等表述）
  • 提及的UI变更、API变更或数据模型变更
  • 边缘情况或错误处理需求
  • 非功能性需求（性能、安全、可访问性）
生成编号格式的需求列表：
R1: <需求描述>
R2: <需求描述>
...
若Issue描述模糊或无明确需求，可结合Issue标题和上下文推断预期行为，但需明确标记推断的需求。

7. Fetch Diff

7. 获取代码差异（Diff）

If a diff file path was provided as input, read the diff from that file instead of fetching it. Skip the commands below and proceed to Step 8.
If 
MODE=remote
:
Get the full diff for the pull request:
bash
gh pr diff $PR_NUMBER
Also review the list of changed files from Step 3 to understand the scope of changes.
If 
MODE=local
:
Get the full diff for local changes (both staged and unstaged):
bash
git diff HEAD
Also review the list of changed files from Step 3 to understand the scope of changes.
若输入中提供了diff文件路径，则直接读取该文件的内容，跳过以下命令，直接进入步骤8。
若
MODE=remote
：
获取PR的完整代码差异：
bash
gh pr diff $PR_NUMBER
同时需查看步骤3中获取的变更文件列表，了解变更范围。
若
MODE=local
：
获取本地变更的完整代码差异（已暂存和未暂存内容）：
bash
git diff HEAD
同时需查看步骤3中获取的变更文件列表，了解变更范围。

8. Analyze Coverage

8. 分析需求覆盖情况

For each requirement from Step 6, determine whether the diff addresses it:
  • Covered: The diff contains code changes that directly implement the requirement
  • Partially covered: The diff addresses some aspects but misses edge cases or details
  • Not covered: No code changes in the diff relate to this requirement
Use evidence from the diff to justify each assessment. Do not speculate -- base judgments on actual code changes.
针对步骤6中提取的每个需求，判断代码差异是否满足该需求：
  • 已覆盖：代码变更直接实现了该需求
  • 部分覆盖：代码变更仅满足了需求的部分内容，遗漏了边缘情况或细节
  • 未覆盖：代码变更中无与该需求相关的内容
需基于代码差异中的实际内容进行判断，不得主观猜测，需提供判断依据。

9. Produce Report

9. 生成报告

Generate one of two outputs based on the analysis.
If all requirements are covered (100% coverage):
MODE=remote
:
undefined
根据分析结果生成以下两种输出之一。
若所有需求均已覆盖（100%覆盖）：
MODE=remote
：
undefined

PR Requirements Coverage: 100%

PR需求覆盖情况：100%

All requirements from issue #<ISSUE_NUMBER> are implemented in PR #<PR_NUMBER>.
Issue #<ISSUE_NUMBER>中的所有需求均已在PR #<PR_NUMBER>中实现。

Requirements

需求列表

#RequirementStatus
R1<description>Covered
R2<description>Covered
编号需求描述状态
R1<描述>已覆盖
R2<描述>已覆盖

Summary

总结

<2-3 sentences confirming that the PR fully addresses the issue, highlighting key implementation decisions>

**`MODE=local`:**
<2-3句话确认PR完全满足Issue需求，重点说明关键实现决策>

**`MODE=local`：**

Local Requirements Coverage: 100%

本地变更需求覆盖情况：100%

All requirements from issue #<ISSUE_NUMBER> are implemented in local changes on branch ${BRANCH_NAME}.
Issue #<ISSUE_NUMBER>中的所有需求均已在分支${BRANCH_NAME}的本地变更中实现。

Requirements

需求列表

#RequirementStatus
R1<description>Covered
R2<description>Covered
编号需求描述状态
R1<描述>已覆盖
R2<描述>已覆盖

Summary

总结

<2-3 sentences confirming that the local changes fully address the issue, highlighting key implementation decisions>

**If any requirements are missing or partially covered:**

**`MODE=remote`:**
<2-3句话确认本地变更完全满足Issue需求，重点说明关键实现决策>

**若存在未覆盖或部分覆盖的需求：**

**`MODE=remote`：**

PR Requirements Coverage: <percentage>%

PR需求覆盖情况：<百分比>%

PR #<PR_NUMBER> does not fully implement issue #<ISSUE_NUMBER>.
PR #<PR_NUMBER>未完全实现Issue #<ISSUE_NUMBER>的需求。

Requirements

需求列表

#RequirementStatusNotes
R1<description>Covered
R2<description>Not covered<what is missing>
R3<description>Partially covered<what is incomplete>
编号需求描述状态备注
R1<描述>已覆盖
R2<描述>未覆盖<遗漏内容说明>
R3<描述>部分覆盖<未完成内容说明>

Missing Implementation

待实现内容

<For each uncovered or partially covered requirement, describe specifically what code changes are needed to complete the implementation>
<针对每个未覆盖或部分覆盖的需求，具体说明需要补充的代码变更内容>

Summary

总结

<2-3 sentences describing the overall gap between the issue requirements and the PR implementation>

**`MODE=local`:**
<2-3句话说明Issue需求与PR实现之间的整体差距>

**`MODE=local`：**

Local Requirements Coverage: <percentage>%

本地变更需求覆盖情况：<百分比>%

Local changes on branch ${BRANCH_NAME} do not fully implement issue #<ISSUE_NUMBER>.
分支${BRANCH_NAME}的本地变更未完全实现Issue #<ISSUE_NUMBER>的需求。

Requirements

需求列表

#RequirementStatusNotes
R1<description>Covered
R2<description>Not covered<what is missing>
R3<description>Partially covered<what is incomplete>
编号需求描述状态备注
R1<描述>已覆盖
R2<描述>未覆盖<遗漏内容说明>
R3<描述>部分覆盖<未完成内容说明>

Missing Implementation

待实现内容

<For each uncovered or partially covered requirement, describe specifically what code changes are needed to complete the implementation>
<针对每个未覆盖或部分覆盖的需求，具体说明需要补充的代码变更内容>

Summary

总结

<2-3 sentences describing the overall gap between the issue requirements and the local changes>
undefined
<2-3句话说明Issue需求与本地变更之间的整体差距>
undefined

10. Report to User

10. 向用户反馈结果

If 
MODE=remote
:
Present the coverage report from Step 9. Include:
  • The issue number and title for context
  • The PR URL for reference
  • The coverage percentage
  • Clear next steps if coverage is incomplete
If 
MODE=local
:
Present the coverage report from Step 9. Include:
  • The issue number and title for context
  • The branch name and list of changed files
  • The coverage percentage
  • Clear next steps if coverage is incomplete
若
MODE=remote
：
展示步骤9生成的覆盖报告，需包含：
  • 用于上下文参考的Issue编号和标题
  • 用于参考的PR URL
  • 需求覆盖百分比
  • 若覆盖不完整，需提供明确的下一步操作建议
若
MODE=local
：
展示步骤9生成的覆盖报告，需包含：
  • 用于上下文参考的Issue编号和标题
  • 分支名称和变更文件列表
  • 需求覆盖百分比
  • 若覆盖不完整，需提供明确的下一步操作建议

Important Notes

重要说明

  • Never fabricate requirements that are not present or implied in the issue
  • If the issue lacks acceptance criteria, clearly state which requirements were inferred from context
  • Do not evaluate code quality -- this skill only checks implementation completeness against the issue description
  • For issues with sub-tasks or linked child issues, only evaluate the requirements in the specific linked issue
  • When multiple issues are linked, report coverage for each issue separately
  • In 
    MODE=local
    , the diff comes from 
    git diff HEAD
    (staged + unstaged changes) instead of a PR diff. The issue must be provided by the user or extracted from the branch name — if neither yields a result, inform the user and stop
  • 不得伪造Issue中未提及或未隐含的需求
  • 若Issue缺少验收标准，需明确说明哪些需求是从上下文推断而来
  • 不得评估代码质量——该工具仅检查代码实现是否符合Issue描述的需求
  • 对于包含子任务或关联子Issue的主Issue，仅评估当前关联Issue中的需求
  • 若关联多个Issue，需分别生成每个Issue的需求覆盖报告
  • 在
    MODE=local
    模式下，代码差异来自
    git diff HEAD
    （已暂存+未暂存变更）而非PR差异。Issue必须由用户提供或从分支名称中提取——若两者均无法获取，需告知用户并终止操作