triage-issue

name	triage-issue
description	通过探索代码库对 Bug/Issue 进行排查归因，并基于 TDD 方式生成修复计划，同时创建对应的 GitHub issue。适用于用户报告了 bug、希望创建 issue、提到“triage”，或想调查并规划某个问题的修复方案。

问题排查（Triage Issue）

对用户报告的问题进行调查、定位根因，并创建一个包含 TDD 修复计划的 GitHub issue。该工作流尽量“半自动化”（hands-off）：在调查阶段尽量减少向用户追问。

过程

1. 捕捉问题

从用户处获取该 issue 的简要描述。如果用户还没有提供，请只问一个问题：你现在看到的问题是什么？

在问出这些信息之后，不要再做进一步追问：立刻开始调查。

2. 探索并诊断

使用 Agent 工具（subagent_type=Explore）对代码库进行深入调查。你的目标是找到：

• 哪里表现出问题（入口点、UI、API 响应等）
• 涉及什么代码路径（追踪调用流程）
• 为什么会失败（根因，而不仅仅是表象）
• 有哪些相关代码存在（类似模式、测试、相邻模块）

重点查看：

• 相关源文件及其依赖关系
• 现有测试（哪些被覆盖、哪些缺失）
• 影响文件的近期改动（对相关文件运行 git log）
• 该代码路径中的错误处理逻辑
• 在仓库其他地方是否存在能正常工作的相似模式

3. 确定修复思路

基于你的调查结果，确定：

• 修复根因所需的最小改动
• 受影响的模块/接口
• 需要通过测试验证哪些行为
• 这属于回归（regression）、缺失功能（missing feature）还是设计缺陷（design flaw）

4. 设计 TDD 修复计划

创建一个具体的、按顺序排列的 RED-GREEN 循环列表。每个循环都是一个“竖向切片”（vertical slice）：一次只覆盖一个小的行为修复步骤。

• RED：描述一个捕获“当前行为缺失/错误”的具体测试
• GREEN：描述为让该测试通过所需的最小代码变更

规则：

• 测试应通过公共接口验证行为，而不是依赖实现细节
• 一次一个测试、按竖向切片推进（不要先写完所有测试再一次性写代码）
• 每个测试都应能在内部重构后保持稳定
• 如有需要，最后包含一个重构步骤
• 耐久性（Durability）：只建议能经得起“仓库大幅改动”的修复方式。用“行为/契约（contract）”而不是“内部结构”。对测试断言的是可观察结果（API 响应、UI 状态、用户可见效果），而不是内部状态。
  • 一个好的建议读起来像规范（spec），而不好的建议读起来像 diff（差异补丁）。

5. 创建 GitHub issue

在创建 issue 时使用 gh issue create 并遵循下方模板。不要在创建 issue 之前先让用户审核：直接创建并把 URL 贴给用户。

## 问题（Problem）

清晰描述 bug 或 issue，包括：

• 发生了什么（实际行为）
• 应当发生什么（期望行为）
• 如何复现（如适用）

根因分析（Root Cause Analysis）

描述你调查过程中发现的内容：

• 涉及的代码路径（以模块/行为为单位描述即可）
• 为什么当前实现会失败
• 任何可能的促成因素（contributing factors）

不要在 issue 中写死当前代码布局耦合到具体的文件路径、行号或实现细节。请以“模块、行为与契约”为粒度描述，让 issue 即使在大规模重构后依然可用。

TDD 修复计划（TDD Fix Plan）

用一个按序的数字列表写出 RED-GREEN 循环：

1. RED：写一个测试，来[描述期望行为] GREEN：让该测试通过所需的[最小改动]

2. RED：写一个测试，来[描述下一个期望行为] GREEN：让该测试通过所需的[最小改动]

...

REFACTOR：所有测试通过后，是否还需要进行任何清理（cleanup）？

验收标准（Acceptance Criteria）

• 验收点 1
• 验收点 2
• 所有新增测试都通过
• 现有测试仍然通过

在创建 issue 后，打印 issue 的 URL，并输出一行总结（root cause 的一句话概括）。