Back to Details

triage-issue

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Triage Issue

问题分类处理（Triage Issue）

Investigate a reported problem, find its root cause, and create a GitHub issue with a TDD fix plan. This is a mostly hands-off workflow - minimize questions to the user.
调查已报告的问题，找出其根本原因，并创建一个包含TDD修复计划的GitHub Issue。这是一个基本无需人工干预的工作流——尽量减少向用户提问。

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. 探索与诊断

Use the Agent tool with subagent_type=Explore to 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
使用subagent_type=Explore的Agent工具深入调查代码库。目标是找出：
  • 问题出现的位置（入口点、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循环列表。每个循环是一个垂直切片：
  • RED：描述一个能捕获当前错误/缺失行为的具体测试
  • GREEN：描述使该测试通过所需的最小代码变更
规则：
  • 测试通过公共接口验证行为，而非实现细节
  • 一次一个测试，采用垂直切片方式（而非先写所有测试再写所有代码）
  • 每个测试应能在内部重构后依然有效
  • 如有需要，包含最终的重构步骤
  • 持久性：仅建议能在代码库大幅变更后依然有效的修复方案。描述行为和契约，而非内部结构。测试断言可观察的结果（API响应、UI状态、用户可见效果），而非内部状态。优秀的建议应像一份规范；糟糕的建议则像一份代码差异对比。

5. Create the GitHub issue

5. 创建GitHub Issue

Create a GitHub issue using 
gh issue create
with the template below. Do NOT ask the user to review before creating - just create it and share the URL.
<issue-template>
使用
gh issue create
命令，按照以下模板创建GitHub Issue。创建前无需征求用户审核——直接创建并分享URL。
<issue-template>

Problem

问题

A clear description of the bug or issue, including:
  • What happens (actual behavior)
  • What should happen (expected behavior)
  • How to reproduce (if applicable)
清晰描述bug或问题，包括：
  • 实际发生的情况（实际行为）
  • 预期发生的情况（预期行为）
  • 复现步骤（如适用）

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.
描述调查过程中的发现：
  • 涉及的代码路径
  • 当前代码失败的原因
  • 任何促成因素
请勿包含特定文件路径、行号或与当前代码布局耦合的实现细节。应描述模块、行为和契约。即使在重大重构后，该Issue仍应保持可用性。

TDD Fix Plan

TDD修复计划

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]
编号的RED-GREEN循环列表：
  1. RED：编写一个测试，[描述预期行为] GREEN：[使测试通过的最小变更]
  2. RED：编写一个测试，[描述下一个行为] GREEN：[使测试通过的最小变更]
...
REFACTOR：[所有测试通过后所需的清理工作]

Acceptance Criteria

验收标准

  • Criterion 1
  • Criterion 2
  • All new tests pass
  • Existing tests still pass
</issue-template>
After creating the issue, print the issue URL and a one-line summary of the root cause.
  • 标准1
  • 标准2
  • 所有新测试通过
  • 现有测试仍能通过
</issue-template>
创建Issue后，打印Issue URL和根本原因的一行摘要。