triage-issue

问题分诊

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

前置条件

• gh（GitHub CLI）：项目使用 GitHub 时必需——从 https://cli.github.com 安装，或运行 brew install gh
• glab（GitLab CLI）：项目使用 GitLab 时必需——从 https://gitlab.com/gitlab-org/cli 安装，或运行 brew install glab

何时使用此技能

在以下情况下启用此技能：

• 用户报告了 Bug 或意外行为
• 用户说“分诊”或“调查这个问题”
• 用户遇到问题后想提交问题
• 用户想了解根本原因并规划修复方案
• 用户要求在调查后创建 Bug 报告

流程

1. 记录问题

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

暂时不要提出后续问题。立即开始调查。

2. 探索并诊断

深入调查代码库。目标是找出：

• 在哪里出现 Bug（入口点、UI、API 响应）
• 涉及哪些代码路径（追踪执行流程）
• 为何失败（根本原因，而不只是症状）
• 存在哪些相关代码（类似模式、测试、相邻模块）

检查：

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

3. 确定修复方案

根据调查结果，确定：

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

4. 设计 TDD 修复计划

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

• RED：描述一个能捕获异常或缺失行为的具体测试
• GREEN：描述使该测试通过所需的最小代码改动

规则：

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

5. 检测平台

创建问题前，检测项目使用 GitLab 还是 GitHub：

1. 检查 GitLab 标志：
   • 仓库根目录存在 .gitlab-ci.yml 文件
   • Git 远程 URL 中包含 gitlab（例如 git remote -v）
2. 检查 GitHub 标志：
   • 仓库根目录存在 .github/ 目录
   • Git 远程 URL 中包含 github.com（例如 git remote -v）
3. **兜底处理：**如果检测到两者或都未检测到，请询问用户：“这个项目似乎同时使用 GitLab 和 GitHub（或者我无法判断使用哪个平台）。你希望我在哪个平台创建问题？”

6. 创建问题

在检测到的平台上创建问题。创建前不要请用户审核——直接创建并分享 URL。

对于 GitHub

使用 gh issue create 和下面的问题模板。

对于 GitLab

使用 GitLab CLI（glab issue create）或通过 CLI 调用 GitLab API。你需要 project_id（经过 URL 编码的路径，例如 group/project，或数字 ID）。如果不确定，可根据 Git 远程 URL 推断。

问题模板

两个平台都使用此模板（Markdown 格式与 GitLab 和 GitHub 均兼容）：

## Problem

A clear description of the bug or issue, including:
- What happens (actual behavior)
- What should happen (expected behavior)
- How to reproduce (if applicable)

## Root Cause Analysis

Describe what you found during investigation:
- The code path involved
- Why the current code fails
- Any contributing factors

Do NOT include specific file paths, line numbers, or implementation details that couple to current code layout. Describe modules, behaviors, and contracts instead. The issue should remain useful even after major refactors.

## TDD Fix Plan

A numbered list of RED-GREEN cycles:

1. **RED**: Write a test that [describes expected behavior]
   **GREEN**: [Minimal change to make it pass]

2. **RED**: Write a test that [describes next behavior]
   **GREEN**: [Minimal change to make it pass]

...

**REFACTOR**: [Any cleanup needed after all tests pass]

## Related Issues

[Link to any existing issues that reported this bug or are related. Use `#<number>` for same-project references, or full URLs for cross-project references. If this was reported in an issue tracker, link to the original report here.]

## Acceptance Criteria

- [ ] Root cause is fixed, not just the symptom
- [ ] All new tests pass
- [ ] Existing tests still pass
- [ ] [Additional criteria specific to this bug]

平台特定说明

GitHub：

• 使用 bug、triage 或项目专属标签
• gh issue create 命令支持 --title、--body 和 --label 标志
• 使用 #<number> 语法关联相关议题
• 在 PR 描述中使用“Fixes #XX”引用修复该问题的 PR

GitLab：

• 使用 bug、priority::high、status::triage 等作用域标签
• 同一项目内使用 #<number>，跨项目使用 group/project#<number> 关联相关议题
• 在 MR 描述中使用“Closes #XX”引用修复该问题的 MR
• 如果可使用可自托管的 GitLab 实例，请在所有引用中使用其实例 URL

7. 汇报结果

创建议题后：

1. 输出议题 URL
2. 用一句话总结根本原因
3. 如果该错误最初是在现有议题中报告的，请说明新的分类议题已链接回该议题

关键规则

• 先调查，后提问。 不要频繁向用户提问。请自行探索代码库，仅在确实无法继续时才询问用户。
• 议题描述中不要包含文件路径。 重构后文件路径可能失效。应描述模块、行为和契约。即使代码库发生演变，议题仍应有参考价值。
• 修复计划必须基于 TDD。 每项修复都必须描述为一系列 RED-GREEN 循环。不要给出含糊的“修复错误”指示。
• 持久性优先于精确性。 优质议题应体现行为规范；糟糕的议题则像是针对当前代码的差异说明。
• 关联现有议题。 如果用户提到了现有议题编号，或你在调查中发现了相关议题，务必在“Related Issues”部分中关联它。
• 每个根本原因对应一个议题。 如果调查发现多个彼此独立的错误，请为每个错误分别创建议题。