bug-capture

bug-capture

将对话转化为问题报告，确保即使项目经历重大重构，报告仍然易于理解。

流程

1. 先倾听，再尽量少地澄清

让用户用自己的话描述问题。最多提出两个简短的澄清问题，从以下内容中选择：

• 预期行为与实际行为。
• 如果描述中尚未明确，询问具体的复现步骤。
• 发生频率：必现、偶发，还是只发生过一次。

如果描述已经回答了这些问题，就直接创建问题报告。过度询问会让报告者为你的不确定性买单。

2. 并行探索

在用户回答的同时，开始探索相关区域。目标不是提出修复方案，而是熟悉项目自己的词汇——代码库在描述此功能时使用的名词和动词——这样问题报告读起来就像是由维护者撰写的。

如果仓库有术语表文件（常见名称：GLOSSARY.md、UBIQUITOUS_LANGUAGE.md、docs/domain.md），请先阅读。

3. 创建报告前检查重复问题

运行 gh issue list --search "<key phrase>" --state all --limit 10。如果有匹配的未关闭问题或近期关闭的问题，告知用户，并询问是否改为添加评论，而不是创建新问题。不要默默跳过创建报告这一步。

4. 决定：创建单个问题还是拆分

如果报告包含两个或更多相互独立的故障模式，且不同贡献者可以并行修复，则拆分。若所有症状都源于同一个错误行为，则保留为一个问题。

如果要拆分，请按依赖顺序创建问题，这样每个子问题都能引用真实的父问题编号，并标注准确的 Blocked by 链接。不要为了让问题树看起来更整齐而虚构依赖关系。

5. 使用 gh issue create 创建问题

无需让用户审核草稿，直接创建问题。然后把 URL 发给用户。

单个问题模板

## What happened
<observed behavior, in domain terms>

## What I expected
<expected behavior>

## Reproduction
1. <step>
2. <step>
3. <step>

## Context
<anything that narrows where the bug lives, in domain terms — e.g.
"only affects the import path, not the export path">

子问题模板

## Parent
#<parent-number>

## What is wrong
<one behavior, narrow slice>

## What I expected
<expected for this slice>

## Reproduction
1. <step>

## Blocked by
<#issue or "none — independent">

## Context
<notes that apply only to this slice>

6. 每个问题正文都必须遵守的规则

• 不要包含文件路径、行号、函数名称或 PR 编号。这些信息会过时。描述行为，而不是代码。
• 使用项目的领域术语，而非通用技术术语。“同步工作进程丢弃了补丁”比“applyPatch() 抛出异常”更好。
• 必须提供复现步骤。如果无法推导出来，创建问题前再向用户询问一次。
• 以 30 秒内读完为目标。删除所有无助于维护者判断是否要处理的内容。

7. 继续处理

每创建一个问题后，打印 URL，并询问是否还有下一个问题。不要在一次创建过程中批量处理多份报告——每个 Bug 都应有自己的问题范围。