bug-report

!bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys automation

自动化模式：解析 modes.automation（project.local.yaml → project.yaml → 默认值 collaborative）。每次调用 AskUserQuestion 和 每次文件写入都遵循 .claude/docs/automation-modes.md （collaborative 总是提问 · guided 仅在重大事项上提问 · autonomous 记录后继续； automation_always_ask 类别总是先提问）。

Bug 报告

仅起草。 此技能会将报告写入 production/qa/bugs/。如果问题原因在引擎、插件或其他供应商的代码中，请在 Notes 下为其问题跟踪器起草报告，然后到此为止：绝不要在对方的代码仓库中提交、开启或评论问题或拉取请求。由用户提交。

阶段 1：解析参数

根据参数确定模式：

• 没有关键词 → 描述模式：根据提供的描述生成结构化 Bug 报告
• analyze [path] → 分析模式：读取目标文件并识别潜在 Bug
• verify [BUG-ID] → 验证模式：确认报告中提及的修复是否确实解决了 Bug
• close [BUG-ID] → 关闭模式：将已验证的 Bug 标记为已关闭，并记录解决方案

如果未提供参数，请先询问用户对 Bug 的描述。

---

阶段 2A：描述模式

1. 解析描述，提取关键信息：发生了什么问题、何时发生、如何复现，以及预期行为是什么。

2. 使用 Grep/Glob 搜索代码库中的相关文件，以补充上下文（受影响的系统、可能相关的文件）。

3. 起草 Bug 报告：

# Bug Report

## Summary
**Title**: [Concise, descriptive title]
**ID**: BUG-[NNNN]
**Severity**: [S1-Critical / S2-High / S3-Medium / S4-Low]
**Priority**: [P1-Fix this sprint / P2-Fix soon / P3-Backlog / P4-Won't fix]
**Status**: Open
**Reported**: [Date]
**Reporter**: [the reporter's name as the user gives it, else `—`; never an email address or account ID taken from the session]

## Classification
- **Category**: [Gameplay / UI / Audio / Visual / Performance / Crash / Network]
- **System**: [Which game system is affected — when the bug spans systems, the one whose code must change; the others go under Related systems]
- **Frequency**: [Always / Often (>50%) / Sometimes (10-50%) / Rare (<10%)]
- **Regression**: [Yes/No/Unknown -- was this working before?]

## Environment
- **Build**: [Version or commit hash]
- **Platform**: [OS, hardware if relevant]
- **Scene/Level**: [Where in the game]
- **Game State**: [Relevant state -- inventory, quest progress, etc.]

## Reproduction Steps
**Preconditions**: [Required state before starting]

1. [Exact step 1]
2. [Exact step 2]
3. [Exact step 3]

**Expected Result**: [What should happen]
**Actual Result**: [What actually happens]

## Technical Context
- **Likely affected files**: [List of files based on codebase search]
- **Related systems**: [What other systems might be involved]
- **Possible root cause**: [If identifiable from the description]

## Evidence
- **Logs**: [Relevant log output if available]
- **Visual**: [Description of visual evidence]

## Related Issues
- [Links to related bugs or design documents]

## Notes
[Any additional context or observations]

严重程度和优先级标签使用 /bug-triage 中的 S 和 P 编号及名称；该技能会从本文件中解析这些内容。如果 P4-Won't fix，它表示其 P4 — Won't fix / Deferred（已接受的风险），而不是愿望清单。如果更改任一等级体系，也要同步更改 .claude/skills/bug-triage/SKILL.md。

---

阶段 2B：分析模式

1. 读取参数中指定的目标文件。

2. 识别潜在 Bug：空引用、差一错误、竞态条件、未处理的边缘情况、资源泄漏、状态转换错误。

3. 对于每个潜在 Bug，使用上述模板生成 Bug 报告，并填写可能的触发场景和建议的修复方案。

---

阶段 2C：验证模式

按编号查找 Bug 文件，此处和 close 模式均如此：Glob production/qa/bugs/BUG-*.md，并选取编号与 [BUG-ID] 匹配的文件， 不论其前导零数量如何；较早的带 slug 的三位数文件也按编号查找。如果 没有匹配项，则停止：「production/qa/bugs/ 中没有 Bug [BUG-ID]。」结论：已阻止 ——不存在此 Bug。

读取该文件。提取复现步骤和预期结果。

1. 重新执行复现步骤——使用 Grep/Glob 检查所述根因代码路径是否仍然存在。如果修复已移除或更改该路径，记录此更改。
2. 运行相关测试——如果该 Bug 所属系统在引擎的测试根目录中有测试文件（Godot：tests/，Unity：Assets/Tests/，Unreal：Source/<Module>/Private/Tests/ — .claude/docs/directory-structure.md），则使用 Bash 和 project.yaml 中的 commands.test 运行测试；在运行器允许的情况下，将测试范围缩小到受影响的套件——绝不要凭记忆写运行器命令行，因为这样会漏掉引擎所需的标志（gdUnit4 若没有 --remote-debug tcp://127.0.0.1:0 就会挂起）——并报告通过或失败。若 commands.test 未设置 → 未运行测试：指出未设置的键，并继续步骤 3。
3. 检查回归——在代码库中搜索是否出现了导致该 Bug 的模式。
4. 手动验证——当没有运行相关测试时（没有测试覆盖该 Bug——在 qa.level 免除测试时通常如此——commands.test 未设置，或运行未完成），或 Bug 的 Category 为 Visual 或 UI（其外观没有自动化测试可检查）时，通过 AskUserQuestion 提问：「你是否已在包含此修复的构建版本上执行复现步骤（见 [bug file]）？是哪个构建版本？」—— [No longer occurs] / [Still occurs] / [Not played yet]。 按用户提供的内容记录回答和构建版本；代码路径已更改，绝不能视为用户的回答。 作为子 Agent 运行？ qa-lead 会预加载此技能，而子 Agent 没有 AskUserQuestion。请以问题和三个选项的简短列表结束回复，暂不提供结论：调用你的人会询问用户，结论须等到收到回答后再给出。

给出验证结论：

• 已验证修复——所有适用检查均表明 Bug 已消失：任何相关测试都已运行并通过；且在步骤 4 提问时，用户已针对指定构建版本回答 [No longer occurs]。若未运行测试，则仅凭这次实际测试即可完成验证——这属于手动验证，并应记录为 [user], manual, build [X]。仅代码路径已更改绝不算通过
• 仍然存在——相关测试在该 Bug 的案例中失败，或用户回答 [Still occurs]；修复未能解决此问题
• 无法验证——步骤 4 的回答为 [Not played yet]：说明缺少什么或无法运行什么（没有相关测试、commands.test 未设置、运行未完成、Bug 属于 Visual 或 UI），并说明实际执行复现步骤即可确定结果——执行后再次运行 /bug-report verify [BUG-ID]

询问：「我可以更新 production/qa/bugs/[bug file]，将 Status 设为 Verified Fixed / Still Present / Cannot Verify 吗？」——填写上文找到的文件名，不论其前导零数量或 slug。设置 Status 时，在其下方写入一行 **Verified by**:：[test file(s)] — ran and passed；若为手动验证，则写入 [user], manual, build [X]。

如果为 STILL PRESENT：重新打开该 Bug，将 Status 设回 Open，并建议重新运行 /hotfix [BUG-ID]。

阶段 2D：关闭模式

按照 verify 模式中的编号读取 bug 文件。关闭前确认 Status 为 Verified Fixed。如果状态不是该值，则停止并提示：“关闭 Bug [ID] 前，必须先将其标记为 Verified Fixed。请先运行 /bug-report verify [BUG-ID]。”

显示下方的关闭记录和 Status 更改，然后询问：“可以将 production/qa/bugs/[bug file] 更新为 Closed 吗？”在获得肯定答复前，不得写入任何内容；如果用户回答否，则停止——该 bug 保持 Verified Fixed 状态。

如果用户回答是，则将关闭记录追加到 bug 文件中：

## Closure Record
**Closed**: [date]
**Resolution**: Fixed — [one-line description of what was changed]
**Fix commit / PR**: [if known]
**Verified by**: [the verify record's `**Verified by**:` line — the test that ran and passed, or "[user], manual, build [X]"]
**Closed by**: [user]
**Regression test**: [test file path, or "Manual verification" when verify recorded a manual play]
**Status**: Closed

然后将顶层的 **Status**: 字段更新为 **Status**: Closed。

关闭后，检查 production/qa/bug-triage-*.md — 如果该 bug 出现在未关闭的分类报告中，提示：“Bug [ID] 在分类报告中有引用。请运行 /bug-triage 以刷新未关闭 bug 的数量。”

---

阶段 3：保存报告

向用户展示已完成的 bug 报告。

在询问前分配 ID： Glob production/qa/bugs/BUG-*.md，取最大编号并加 1，补零至四位数（若没有文件，则使用 BUG-0001）。一次运行中有多份报告（分析模式）时，从该编号开始依次分配连续 ID，每份一个 — 绝不重复使用同一 ID。

询问：“可以将其写入 production/qa/bugs/BUG-[NNNN].md 吗？”如果有多份报告，只询问一次并列出所有文件：“可以将这些报告写入 production/qa/bugs/BUG-[NNNN].md、production/qa/bugs/BUG-[NNNN+1].md、……吗？”

如果用户回答是，则写入文件；如有需要，创建目录。判定：COMPLETE — bug 报告已归档。

如果用户回答否，则在此停止。判定：BLOCKED — 用户拒绝写入。

---

阶段 4：后续步骤

保存后，根据模式提出建议：

归档后（描述/分析模式）：

• 运行 /bug-triage，与现有未关闭 bug 一起确定优先级
• 如果是 S1 或 S2：运行 /hotfix [BUG-ID]，启动紧急修复工作流

修复 bug 后（开发者确认修复已完成）：

• 运行 /bug-report verify [BUG-ID] — 确认修复确实有效后再关闭
• 未经验证，绝不将 bug 标记为已关闭 — 未通过验证的修复仍处于 Open 状态

verify 返回 CANNOT VERIFY 后：

• 在包含修复的构建版本上执行复现步骤，然后再次运行 /bug-report verify [BUG-ID] 并回答其问题

verify 返回 VERIFIED FIXED 后：

• 运行 /bug-report close [BUG-ID] — 写入关闭记录并更新状态
• 运行 /bug-triage，刷新未关闭 bug 的数量，并将其从活动列表中移除