---
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 贴给用户。

<issue-template>
## 问题（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-template>

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