wtf.report-bug

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Report Bug

报告Bug

File a structured Bug issue from a QA finding. Core value: the Gherkin scenario that failed becomes the reproducible test evidence, and the originating Task and Feature are linked automatically so nothing loses its context.

基于QA发现的问题提交结构化的Bug工单。核心价值：失败的Gherkin场景将作为可复现的测试证据，且会自动关联来源任务（Task）和需求（Feature），确保上下文不丢失。

Process

流程

0. GitHub CLI setup

0. GitHub CLI 配置

Run steps 1–2 of

../references/gh-setup.md

(install check and auth check). Stop if

gh

is not installed or not authenticated. Extensions are not required for this skill.

Skip this step if invoked from

verify-task

or another skill that already ran gh-setup this session.

执行

../references/gh-setup.md

中的步骤1–2（安装检查与身份验证检查）。若未安装

gh

或未完成身份验证，则停止操作。本Skill无需使用扩展。

若从

verify-task

或本次会话中已执行过gh-setup的其他Skill调用本功能，可跳过此步骤。

1. Identify the source

1. 确定来源

If called from
verify-task
: the task number and failing scenario(s) are already in context — skip to step 2. Do not ask the questions below.

If invoked directly:

Ask in a single message:

"What is the bug? (one sentence)"
"Which Task does this trace back to? (issue number, or 'unknown')"

If a task number is known, fetch the Task first, extract the Feature number from its Context section, then fetch the Feature:

bash

gh issue view <task_number>    # Gherkin, Contracts, ACs, DoD — also yields feature number

**若从

verify-task

调用：**任务编号和失败场景已在上下文中——直接跳至步骤2，无需询问以下问题。

若直接调用：

在一条消息中询问：

“Bug内容是什么？（一句话描述）”
“该Bug追溯至哪个任务？（任务编号，或填写‘未知’）”

若已知任务编号，先获取该任务信息，从其上下文部分提取需求编号，再获取需求信息：

bash

gh issue view <task_number>    # 获取Gherkin、契约、验收标准、完成定义——同时可得到需求编号

Extract feature number, then:

提取需求编号后执行：

gh issue view <feature_number> # ACs, user stories for expected behavior context

undefined

gh issue view <feature_number> # 获取验收标准、用户故事，作为预期行为的上下文

undefined

2. Identify the failing scenario(s)

2. 确定失败场景

If the Task has Gherkin, present the full scenario list and call

AskUserQuestion

with

question: "Which scenarios failed?"

header: "Failing scenarios"

, and

options

pre-filled with the scenario names from the Task (one option per scenario), plus

{label: "New — not covered by existing scenarios", description: "This bug isn't covered by the current Gherkin"}

For each failing scenario, note:

The scenario name
The file path of the automated test (if it exists) or "manual"
The failing step (the first Then / When that did not hold)

If no Gherkin exists for this bug, skip this step and rely on step 3.

若任务包含Gherkin内容，展示完整场景列表，并调用

AskUserQuestion

，参数为：

question: "哪些场景失败了？"

，

header: "失败场景"

，

options

预填充任务中的场景名称（每个场景为一个选项），再添加

{label: "新增——未被现有场景覆盖", description: "该Bug未被当前Gherkin场景覆盖"}

。

针对每个失败场景，记录：

场景名称
自动化测试的文件路径（若存在）或标记为“手动”
失败步骤（第一个未通过的Then/When步骤）

若该Bug无对应的Gherkin场景，跳过此步骤，直接执行步骤3。

3. Gather bug details

3. 收集Bug详情

If called from
verify-task
and all six details below are already in context, skip this step entirely.

Otherwise, gather each unknown item one at a time using

AskUserQuestion

, omitting any item already known:

a. Observed behavior — call
```
AskUserQuestion
```
with
```
question: "What was the exact behavior you observed?"
```
,
```
header: "Actual behavior"
```
, and
```
options
```
pre-filled with 1–2 plausible failure descriptions inferred from the scenario context.

b. Expected behavior — call

AskUserQuestion

with

question: "What did you expect to happen instead?"

header: "Expected behavior"

, and

options

pre-filled with the relevant Gherkin

Then

step or AC text if available.

c. Reproduction steps — call

AskUserQuestion

with

question: "What are the reproduction steps?"

header: "Repro steps"

, and

options: [{label: "I'll type them out", description: "Enter numbered steps"}]

d. Contract violation — call
```
AskUserQuestion
```
with
```
question: "Is any contract violated?"
```
,
```
header: "Contract"
```
, and
```
options
```
pre-filled with contract names from the Task (e.g. API schema name, event name), plus
```
{label: "None identified"}
```
.
e. Regression risk — call
```
AskUserQuestion
```
with
```
question: "What else might break if we fix this?"
```
,
```
header: "Regression risk"
```
, and
```
options
```
pre-filled with adjacent areas found in the codebase or related Aggregates.

f. Suggested fix — call

AskUserQuestion

with

question: "Do you have a suggested fix in mind?"

header: "Suggested fix"

, and

options: [{label: "No suggestion", description: "Leave blank"}]

若从
verify-task
调用且以下六项详情均已在上下文中，可完全跳过此步骤。

否则，使用

AskUserQuestion

逐项收集未知信息（已明确的信息可省略）：

a. 实际行为 —— 调用
```
AskUserQuestion
```
，参数为：
```
question: "你观察到的具体行为是什么？"
```
，
```
header: "实际行为"
```
，
```
options
```
预填充1-2个根据场景上下文推断出的合理故障描述。
b. 预期行为 —— 调用
```
AskUserQuestion
```
，参数为：
```
question: "你原本预期会发生什么？"
```
，
```
header: "预期行为"
```
，
```
options
```
预填充相关的Gherkin
```
Then
```
步骤或验收标准文本（若可用）。

c. 复现步骤 —— 调用

AskUserQuestion

，参数为：

question: "复现步骤是什么？"

，

header: "复现步骤"

，

options: [{label: "我将手动输入", description: "输入编号步骤"}]

。

d. 契约违反 —— 调用
```
AskUserQuestion
```
，参数为：
```
question: "是否存在契约违反情况？"
```
，
```
header: "契约"
```
，
```
options
```
预填充任务中的契约名称（如API schema名称、事件名称），再添加
```
{label: "未发现违反"}
```
。
e. 回归风险 —— 调用
```
AskUserQuestion
```
，参数为：
```
question: "修复此Bug可能会影响哪些其他功能？"
```
，
```
header: "回归风险"
```
，
```
options
```
预填充代码库中相关的相邻模块或聚合根（Aggregates）。

f. 建议修复方案 —— 调用

AskUserQuestion

，参数为：

question: "你是否有建议的修复方案？"

，

header: "建议修复方案"

，

options: [{label: "无建议", description: "留空"}]

。

4. Map to Ubiquitous Language

4. 映射至通用语言（Ubiquitous Language）

Review the bug description and reproduction steps. If implementation vocabulary has crept in (e.g. "the database returned null", "the HTTP 500 response", "the JSON field"), restate in domain terms that match the Task's Ubiquitous Language (e.g. "the Order could not be found", "the Payment Settlement failed", "the Shipment Reference was missing").

Confirm the restatement with the user before proceeding.

When called from
verify-task
with multiple failures to file: apply the restatement silently — do NOT ask for confirmation. Note the language changes made in the draft instead of asking the user to approve them. This prevents an interrogation when processing multiple bugs in sequence.

审核Bug描述和复现步骤。若出现实现层面的术语（如“数据库返回null”、“HTTP 500响应”、“JSON字段”），需转换为与任务通用语言匹配的领域术语（如“无法找到订单”、“支付结算失败”、“运单参考号缺失”）。

继续下一步前，需与用户确认转换后的表述。

**若从
verify-task
调用且需提交多个故障：**自动完成表述转换——无需询问用户确认。只需在草稿中记录语言转换的内容，避免在批量处理Bug时反复询问用户。

5. Find linked test files

5. 查找关联测试文件

Use the Grep tool to locate:

Automated test files that cover the failing Gherkin scenario (search by scenario name or feature area)
Any existing test for the contract section violated

List each file found with a one-line description of what it covers. These become the Test Evidence in the bug report.

使用Grep工具定位：

覆盖失败Gherkin场景的自动化测试文件（按场景名称或需求领域搜索）
针对违反契约部分的现有测试文件

列出找到的每个文件，并附上一行描述说明其覆盖范围。这些文件将作为Bug报告中的测试证据。

6. Draft the Bug report

6. 撰写Bug报告草稿

Read the BUG template first:

bash

undefined

先读取BUG模板：

bash

undefined

Read .github/ISSUE_TEMPLATE/BUG.md

读取 .github/ISSUE_TEMPLATE/BUG.md


Use only the markdown body below the second `---` delimiter (ignore YAML frontmatter).

Fill in all sections:

**Related**

- Feature: #\<feature_number\> (if known)
- Task: #\<task_number\> (if known)
- Failing test(s): list each file path (or "manual" with reproduction steps)

**Expected Behavior**
Quote the relevant Gherkin `Then` step or Feature AC verbatim, then add a plain-language restatement.

**Actual Behavior**
Describe in domain terms what happened instead. Include any observable symptom (error message, wrong state, missing event).

**Steps to Reproduce**
Concrete numbered steps — exact inputs, routes, or actions. If from a Gherkin scenario, map Given → setup, When → action, Then → the failing assertion.

**Contracts Violated**
Paste the relevant contract section from the Task (API schema, event schema, invariant). If none, write "None identified."

**Suggested Fix**
Fill if the QA engineer or developer has a hypothesis. Otherwise leave blank.

**Regression Risk**
List other behaviors, Aggregates, or integration points that touch the same code path and could be affected by a fix.


仅使用第二个`---`分隔符下方的Markdown内容（忽略YAML前置内容）。

填写所有部分：

**关联项**

- 需求：#\<feature_number\>（若已知）
- 任务：#\<task_number\>（若已知）
- 失败测试：列出每个文件路径（或标记为“手动”并附上复现步骤）

**预期行为**

引用相关的Gherkin `Then`步骤或需求验收标准原文，再添加通俗易懂的表述。

**实际行为**

用领域术语描述实际发生的情况。包括所有可观察到的症状（错误信息、异常状态、缺失事件）。

**复现步骤**

具体的编号步骤——明确输入内容、路径或操作。若来自Gherkin场景，将Given映射为准备步骤，When映射为操作步骤，Then映射为失败断言。

**违反的契约**

粘贴任务中的相关契约内容（API schema、事件schema、不变式）。若无，则填写“未发现违反”。

**建议修复方案**

若QA工程师或开发者有假设方案则填写，否则留空。

**回归风险**

列出可能受修复影响的其他功能、聚合根或集成点。

7. Review with user

7. 与用户审核草稿

Show the draft. Then call

AskUserQuestion

with

question: "Does this accurately capture the bug and its impact?"

header: "Review"

, and

options: [{label: "Yes — create the issue", description: "Proceed with bug creation"}, {label: "I have changes", description: "I want to adjust something first"}]

Apply edits, then proceed.

展示草稿内容。然后调用

AskUserQuestion

，参数为：

question: "这份报告是否准确涵盖了Bug及其影响？"

，

header: "审核"

，

options: [{label: "是——创建工单", description: "继续创建Bug工单"}, {label: "我需要修改", description: "我想先调整内容"}]

。

应用修改后，继续下一步。

8. Create the issue

8. 创建工单

Note: the commands below are pseudo-code. Write each body to a temp file with the Write tool, then use
--body-file
to avoid shell quoting issues with multi-line content.

Title generation: Spawn a subagent using the

claude-haiku-4-5

model to generate a concise title from the bug's one-sentence description. Pass in the description and ask for a short title (no prefix emoji/label needed — that is added below). If the subagent returns nothing usable, derive the title directly from the one-sentence description.

bash

gh issue create --title "🐞 Bug: <title>" --body-file /tmp/bug-body.md --label "bug"

If the originating Task is known, add a comment to it linking the bug:

bash

gh issue comment <task_number> --body "🐞 Bug reported: #<bug_number> — <one-line summary>"

Print the Bug issue URL and number.

bash

rm /tmp/bug-body.md

Note: if the
bug
label does not exist on the repo, create it first with
gh label create bug --color d73a4a
before running
gh issue create
.

注意：以下命令为伪代码。使用Write工具将内容写入临时文件，再通过
--body-file
参数避免多行内容的Shell引用问题。

标题生成： 使用

claude-haiku-4-5

模型启动子Agent，根据Bug的一句话描述生成简洁标题。传入描述内容，要求生成简短标题（无需前缀表情/标签——后续会添加）。若子Agent未返回可用内容，则直接从一句话描述中提取标题。

bash

gh issue create --title "🐞 Bug: <title>" --body-file /tmp/bug-body.md --label "bug"

若已知来源任务，在该任务下添加评论关联Bug：

bash

gh issue comment <task_number> --body "🐞 已报告Bug：#<bug_number> — <一句话摘要>"

打印Bug工单的URL和编号。

bash

rm /tmp/bug-body.md

注意：若仓库中不存在
bug
标签，需先执行
gh label create bug --color d73a4a
创建标签，再运行
gh issue create
。

9. Offer next steps

9. 提供后续操作选项

Call

AskUserQuestion

with:

```
question
```
: "What's next?"
```
header
```
: "Next step"

options

[{label: "Report another bug", description: "File another bug from this QA session (default if more failures remain)"}, {label: "Mark Task blocked", description: "Reopen the Task and mark it blocked by this bug"}, {label: "Done", description: "Exit — no further action (default if no more failures remain)"}]

Report another bug → restart from step 2 with the same Task context. Use as default only when the caller (e.g.
```
verify-task
```
step 8) has indicated more failures are pending.

Mark Task blocked → reopen the Task and add a blocking comment:

bash

gh issue reopen <task_number>
gh issue comment <task_number> --body "Blocked by #<bug_number>."

Done (default when no more failures remain) → exit.

调用

AskUserQuestion

，参数为：

```
question
```
: "下一步操作？"
```
header
```
: "下一步"

options

[{label: "报告另一个Bug", description: "从本次QA环节提交另一个Bug（若存在更多故障则默认选择此项）"}, {label: "标记任务阻塞", description: "重新打开任务并标记其被此Bug阻塞"}, {label: "完成", description: "退出——无后续操作（若无更多故障则默认选择此项）"}]

报告另一个Bug → 从步骤2重启，保留相同任务上下文。仅当调用方（如
```
verify-task
```
步骤8）提示存在更多待处理故障时，默认选择此项。

标记任务阻塞 → 重新打开任务并添加阻塞评论：

bash

gh issue reopen <task_number>
gh issue comment <task_number> --body "被#<bug_number>阻塞。"

完成（若无更多故障则默认选择） → 退出。