triage-issue

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Triage Issue

Issue排查

Investigate a reported problem, find its root cause, and create a GitLab or GitHub issue with a TDD fix plan. This is a mostly hands-off workflow -- minimize questions to the user.

调研上报的问题，找到其根本原因，然后创建包含TDD修复方案的GitLab或GitHub issue。这是一个几乎无需用户过多参与的工作流——尽量减少对用户的提问。

When to Use This Skill

何时使用该技能

Activate this skill when:

The user reports a bug or unexpected behavior
The user says "triage" or "investigate this issue"
The user wants to file an issue after encountering a problem
The user wants to understand root cause and plan a fix
The user asks to create a bug report with investigation

满足以下条件时激活该技能：

用户报告了bug或意外行为
用户提到「triage」或「调研这个issue」
用户遇到问题后想要提交issue
用户想要了解根本原因并规划修复方案
用户要求通过调研创建bug报告

Process

流程

1. Capture the Problem

1. 捕获问题

Get a brief description of the issue from the user. If they haven't provided one, ask ONE question: "What's the problem you're seeing?"

Do NOT ask follow-up questions yet. Start investigating immediately.

从用户处获取问题的简要描述。如果用户还没有提供，只问一个问题：「你遇到了什么问题？」

暂时不要追问后续问题，立刻开始调研。

2. Explore and Diagnose

2. 探索与诊断

Deeply investigate the codebase. Your goal is to find:

Where the bug manifests (entry points, UI, API responses)
What code path is involved (trace the flow)
Why it fails (the root cause, not just the symptom)
What related code exists (similar patterns, tests, adjacent modules)

Look at:

Related source files and their dependencies
Existing tests (what's tested, what's missing)
Recent changes to affected files (
```
git log
```
on relevant files)
Error handling in the code path
Similar patterns elsewhere in the codebase that work correctly

深入调研代码库，你的目标是找到：

故障位置：bug的出现位置（入口点、UI、API响应）
涉及代码路径：涉及哪些代码链路（追踪执行流）
故障原因：为什么会失败（要找根本原因，而不仅仅是表面症状）
关联代码：存在哪些相关代码（相似模式、测试用例、相邻模块）

需要查看的内容包括：

相关源文件及其依赖
现有测试用例（覆盖了哪些场景，缺失了哪些场景）
受影响文件的近期变更（相关文件的
```
git log
```
记录）
该代码路径中的错误处理逻辑
代码库中其他运行正常的相似实现模式

3. Identify the Fix Approach

3. 确定修复方案

Based on your investigation, determine:

The minimal change needed to fix the root cause
Which modules/interfaces are affected
What behaviors need to be verified via tests
Whether this is a regression, missing feature, or design flaw

基于你的调研，确定以下内容：

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

4. Design TDD Fix Plan

4. 设计TDD修复计划

Create a concrete, ordered list of RED-GREEN cycles. Each cycle is one vertical slice:

RED: Describe a specific test that captures the broken/missing behavior
GREEN: Describe the minimal code change to make that test pass

Rules:

Tests verify behavior through public interfaces, not implementation details
One test at a time, vertical slices (NOT all tests first, then all code)
Each test should survive internal refactors
Include a final refactor step if needed
Durability: Only suggest fixes that would survive radical codebase changes. Describe behaviors and contracts, not internal structure. Tests assert on observable outcomes (API responses, UI state, user-visible effects), not internal state. A good suggestion reads like a spec; a bad one reads like a diff.

创建具体、有序的红-绿循环列表，每个循环对应一个垂直切片：

红（RED）：描述一个能够复现故障/缺失行为的具体测试用例
绿（GREEN）：描述让该测试用例通过所需的最小代码改动

规则：

测试通过公共接口验证行为，而非测试实现细节
一次只写一个测试，按垂直切片迭代（不要先写完全部测试再写全部代码）
每个测试都应该在内部重构后仍然可用
如有需要，包含最终的重构步骤
持久性：只建议能够在代码库大幅变更后仍然适用的修复方案。描述行为和契约，而非内部结构。测试要断言可观测的结果（API响应、UI状态、用户可见效果），而非内部状态。好的建议读起来像一份规范，差的建议读起来像一份代码差异补丁。

5. Detect the Platform

5. 识别平台

Before creating the issue, detect whether the project uses GitLab or GitHub:

Check for GitLab indicators:
- File
```
.gitlab-ci.yml
```
  exists at the repository root
- Git remote URL contains
```
gitlab
```
  (e.g.,
```
git remote -v
```
  )
Check for GitHub indicators:
- Directory
```
.github/
```
  exists at the repository root
- Git remote URL contains
```
github.com
```
  (e.g.,
```
git remote -v
```
  )
Fallback: If both or neither are detected, ask the user: "This project seems to use both GitLab and GitHub (or I couldn't detect which). Which platform should I create the issue on?"

创建issue前，先识别项目使用的是GitLab还是GitHub：

检查GitLab标识：
- 仓库根目录存在
```
.gitlab-ci.yml
```
  文件
- Git远程仓库URL包含
```
gitlab
```
  （例如执行
```
git remote -v
```
  查看）
检查GitHub标识：
- 仓库根目录存在
```
.github/
```
  文件夹
- Git远程仓库URL包含
```
github.com
```
  （例如执行
```
git remote -v
```
  查看）
兜底方案：如果同时检测到两种标识或者都没检测到，询问用户：「该项目似乎同时使用GitLab和GitHub（或者我无法识别具体平台），我应该在哪个平台上创建issue？」

6. Create the Issue

6. 创建Issue

Create the issue on the detected platform. Do NOT ask the user to review before creating -- just create it and share the URL.

在识别到的平台上创建issue。创建前无需请用户审核——直接创建并分享URL即可。

For GitHub

适用于GitHub

Use

gh issue create

with the issue template below.

使用

gh issue create

命令和下方的issue模板创建。

For GitLab

适用于GitLab

Use the GitLab MCP tools (

gitlab-mcp(create_issue)

) or the GitLab API via CLI. You will need the

project_id

(URL-encoded path like

group/project

or numeric ID). If uncertain, derive it from the git remote URL.

使用GitLab MCP工具（

gitlab-mcp(create_issue)

）或通过CLI调用GitLab API。你需要

project_id

（URL编码的路径，例如

group/project

或者数字ID）。如果不确定，可以从Git远程仓库URL中提取。

Issue Template

Issue模板

Use this template for both platforms (the Markdown format is compatible with both GitLab and GitHub):

markdown

undefined

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

markdown

undefined

Problem

A clear description of the bug or issue, including:

What happens (actual behavior)
What should happen (expected behavior)
How to reproduce (if applicable)

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.

Describe what you found during investigation:

The code path involved
Why the current code fails
Any contributing factors

TDD Fix Plan

A numbered list of RED-GREEN cycles:

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

...

REFACTOR: [Any cleanup needed after all tests pass]

A numbered list of RED-GREEN cycles:

RED: Write a test that [describes expected behavior] GREEN: [Minimal change to make it pass]
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.]

[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]

undefined

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

undefined

Platform-Specific Notes

平台特定说明

GitHub:

Use labels like
```
bug
```
,
```
triage
```
, or project-specific labels
The
```
gh issue create
```
command supports
```
--title
```
,
```
--body
```
, and
```
--label
```
flags
Link related issues with
```
#<number>
```
syntax
Reference PRs that fix the issue with "Fixes #XX" in the PR description

GitLab:

Use scoped labels like
```
bug
```
,
```
priority::high
```
,
```
status::triage
```
Link related issues with
```
#<number>
```
for same-project or
```
group/project#<number>
```
for cross-project
Reference MRs that fix the issue with "Closes #XX" in the MR description
If the self-hosted GitLab instance is available, use its URL for all references

GitHub：

使用
```
bug
```
、
```
triage
```
等标签或者项目特定的标签
```
gh issue create
```
命令支持
```
--title
```
、
```
--body
```
和
```
--label
```
参数
使用
```
#<编号>
```
语法关联相关issue
在PR描述中使用「Fixes #XX」引用修复该issue的PR

GitLab：

使用带范围的标签，例如
```
bug
```
、
```
priority::high
```
、
```
status::triage
```
同项目关联issue使用
```
#<编号>
```
语法，跨项目使用
```
group/project#<编号>
```
语法
在MR描述中使用「Closes #XX」引用修复该issue的MR
如果使用的是自托管GitLab实例，所有引用都使用该实例的URL

7. Report Back

7. 反馈结果

After creating the issue:

Print the issue URL
Print a one-line summary of the root cause
If this bug was originally reported in an existing issue, mention that the new triage issue links back to it

创建issue后：

输出issue的URL
输出一行根本原因的摘要
如果该bug最初是在现有issue中上报的，说明新创建的排查issue已经关联了原issue

Critical Rules

核心规则

Investigate first, ask later. Do not pepper the user with questions. Explore the codebase yourself and only ask the user when you are genuinely stuck.
No file paths in issue descriptions. File paths go stale after refactors. Describe modules, behaviors, and contracts instead. The issue should remain useful even after the codebase evolves.
TDD-based fix plans only. Every fix must be described as a sequence of RED-GREEN cycles. No vague "fix the bug" instructions.
Durability over precision. A good issue reads like a behavioral spec. A bad issue reads like a diff against today's code.
Link to existing issues. If the user mentions an existing issue number, or if you find a related issue during investigation, always link to it in the "Related Issues" section.
One issue per root cause. If investigation reveals multiple independent bugs, create separate issues for each.

**先调研，后提问。**不要频繁向用户提问。先自行探索代码库，只有在确实卡住的时候再询问用户。
**issue描述中不要出现文件路径。**文件路径会在重构后失效。换成描述模块、行为和契约。即使经过大规模重构，该issue仍然应该有参考价值。
**仅使用基于TDD的修复计划。**每个修复方案都必须描述为一系列红-绿循环，不要出现模糊的「修复bug」类指令。
**持久性优先于精确性。**好的issue读起来像一份行为规范，差的issue读起来像针对当前代码的差异补丁。
**关联现有issue。**如果用户提到了现有issue编号，或者你在调研过程中发现了相关issue，一定要在「相关Issue」部分关联它们。
**每个根因对应一个issue。**如果调研发现多个独立的bug，为每个bug单独创建issue。