triage-issue

排查问题

调查已报告的问题，找出根本原因，并创建包含 TDD 修复计划的 GitHub issue。这是一个基本无需用户参与的工作流——尽量减少向用户提问。

流程

1. 记录问题

请用户简要描述问题。如果用户尚未描述，只问一个问题：“你遇到了什么问题？”

此时不要追问。立即开始调查。

2. 探索并诊断

使用 Agent 工具，并将 subagent_type 设为 Explore，深入调查代码库。你的目标是找出：

• 问题出现的位置（入口点、UI、API 响应）
• 涉及的代码路径（追踪调用流程）
• 失败的原因（根本原因，而不只是表面症状）
• 相关代码（相似模式、测试、相邻模块）

检查以下内容：

• 相关源文件及其依赖项
• 现有测试（已测试的内容、缺失的内容）
• 受影响文件的近期变更（对相关文件运行 git log）
• 代码路径中的错误处理
• 代码库中其他地方可正常工作的相似模式

3. 确定修复方案

根据调查结果，确定：

• 修复根本原因所需的最小改动
• 受影响的模块／接口
• 需要通过测试验证的行为
• 这是回归问题、缺失功能还是设计缺陷

4. 设计 TDD 修复计划

创建具体且有序的 RED-GREEN 循环列表。每个循环都是一个垂直切片：

• RED：描述一个能捕捉损坏或缺失行为的具体测试
• GREEN：描述让该测试通过所需的最小代码改动

规则：

• 测试应通过公共接口验证行为，而非实现细节
• 一次编写一个测试，按垂直切片推进（不要先写完所有测试，再编写所有代码）
• 每个测试都应能经受内部重构
• 如有需要，加入最后的重构步骤
• 持久性：只建议能经受代码库彻底变更的修复。描述行为和契约，而非内部结构。测试应断言可观察到的结果（API 响应、UI 状态、用户可见效果），而非内部状态。好的建议读起来像规范；差的建议读起来像差异比较。

5. 创建 GitHub issue

使用下方模板，通过 gh issue create 创建 GitHub issue。创建前不要要求用户审核——直接创建并分享 URL。

问题

清楚描述错误或问题，包括：

• 实际发生的情况
• 预期发生的情况
• 如何复现（如适用）

根本原因分析

描述调查所得：

• 涉及的代码路径
• 当前代码失败的原因
• 任何促成因素

不要包含具体文件路径、行号或与当前代码布局绑定的实现细节。请描述模块、行为和契约。即使经过重大重构，该 issue 仍应具有参考价值。

TDD 修复计划

按编号列出 RED-GREEN 循环：

1. RED：编写一个测试，用于验证［描述预期行为］ GREEN：［让测试通过所需的最小改动］

2. RED：编写一个测试，用于验证［下一个预期行为］ GREEN：［让测试通过所需的最小改动］

...

REFACTOR：［所有测试通过后需要进行的清理工作］

验收标准

• 标准 1
• 标准 2
• 所有新增测试均通过
• 现有测试仍然通过

创建 issue 后，输出 issue URL，并用一句话概述根本原因。