triage-issue

name	triage-issue
description	通过探索代码库以找到根本原因来对 bug 或 issue 进行分类, 然后创建包含基于 TDD 的修复计划的 GitHub issue. 当用户报告 bug, 想要提交 issue, 提到 "排查问题", "问题归类", "triage" 或想要调查并规划问题的修复时使用.

分类 Issue

调查报告的问题, 找到其根本原因, 并创建包含 TDD 修复计划的 GitHub issue. 这是一个大部分不需要干预的工作流程 - 尽量减少对用户的提问.

流程

1. 捕获问题

从用户那里获得问题的简要描述. 如果他们没有提供, 问一个问题: "你看到的问题是什么?"

不要马上问后续问题. 立即开始调查.

2. 探索和诊断

使用 Agent 工具(subagent_type=Explore)深入调查代码库. 你的目标是找到:

• 在哪里 bug 表现出来(入口点, UI, API 响应)
• 什么 代码路径涉及(跟踪流程)
• 为什么 它失败(根本原因, 而不仅仅是症状)
• 什么 相关代码存在(类似模式, 测试, 相邻模块)

查看:

• 相关源文件及其依赖项
• 现有测试(测试了什么, 缺少什么)
• 受影响文件的最近更改(相关文件上的 git log)
• 代码路径中的错误处理
• 代码库中其他地方正常工作的类似模式

3. 确定修复方法

根据你的调查, 确定:

• 修复根本原因所需的最小更改
• 哪些模块/接口受到影响
• 需要通过测试验证哪些行为
• 这是回归, 缺失功能还是设计缺陷

4. 设计 TDD 修复计划

创建一个具体的, 有序的 RED-GREEN 循环列表. 每个循环是一个垂直切片:

• RED: 描述捕获损坏/缺失行为的特定测试
• GREEN: 描述使该测试通过的最小代码更改

规则:

• 测试通过公共接口验证行为, 而不是实现细节
• 一次一个测试, 垂直切片(不是先所有测试, 然后所有代码)
• 每个测试都应该在内部重构后存活
• 如果需要, 包括最终重构步骤
• 持久性: 只建议能在代码库根本性变化后存活的修复. 描述行为和契约, 而不是内部结构. 测试断言可观察的结果(API 响应, UI 状态, 用户可见的效果), 而不是内部状态. 好的建议读起来像规格; 坏的读起来像差异.

5. 创建 GitHub issue

使用 gh issue create 和下面的模板创建 GitHub issue. 不要在创建前要求用户审查 - 只需创建它并分享 URL.

问题

对 bug 或 issue 的清晰描述, 包括:

• 发生了什么(实际行为)
• 应该发生什么(预期行为)
• 如何重现(如果适用)

根因分析

描述你在调查期间发现的内容:

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

不要包含与当前代码布局耦合的特定文件路径, 行号或实现细节. 相反, 描述模块, 行为和契约. 即使在重大重构后, 该 issue 也应该保持有用.

TDD 修复计划

RED-GREEN 循环的带编号列表:

1.** RED**: 编写一个测试 [描述预期行为] GREEN: [使其通过的最小更改]

2.** RED**: 编写一个测试 [描述下一个行为] GREEN: [使其通过的最小更改]

...

REFACTOR: [所有测试通过后需要的任何清理]

验收标准

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

创建 issue 后, 打印 issue URL 和根本原因的单行摘要.