cs-issue-report

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

cs-issue-report

这一阶段做两件事：把用户脑子里的问题落成结构化记录，顺便判断这个问题该走标准路径还是快速通道。

写报告的部分有一条核心原则：只记现象不记根因。用户开始说"我觉得是 XX 组件的问题"时——记下"用户怀疑 XX 组件"作为线索，但不要顺着聊根因。根因要在阶段 2 通过实际读代码确认，不靠脑子里的猜测。混进根因猜测的报告会带偏阶段 2 的分析方向，让分析人围着错误线索绕。

共享路径与命名约定看
codestable/reference/shared-conventions.md
第 0 节和
cs-issue
的"文件放哪儿"节。

This stage has two objectives: Convert the user's problem into a structured record, and determine whether the issue should follow the standard path or fast track.

There is one core principle for writing the report: Record only phenomena, not root causes. When the user says "I think it's a problem with the XX component" — note down "User suspects XX component" as a clue, but do not discuss the root cause further. Root causes must be confirmed by actually reading the code in Stage 2, not based on guesses. Reports mixed with root cause speculations will mislead the analysis direction in Stage 2, causing analysts to waste time on incorrect leads.

Refer to Section 0 of
codestable/reference/shared-conventions.md
and the "Where to place files" section of
cs-issue
for shared paths and naming conventions.

启动检查

Startup Checks

1. 确认是 bug 不是新功能需求

1. Confirm it's a bug, not a new feature request

如果用户描述的是"想加一个 X 功能"，告诉他走

cs-feat

工作流。

If the user describes "wanting to add feature X", inform them to follow the

cs-feat

workflow.

2. 看有没有相关 issue 目录

2. Check for existing issue directories

Glob

codestable/issues/

下的子目录，看有没有同类问题已经记录过。有的话先和用户确认是新建还是更新已有 report。

Glob the subdirectories under

codestable/issues/

to see if similar issues have already been recorded. If yes, first confirm with the user whether to create a new report or update the existing one.

3. 快速通道判断（这是唯一正式判定点）

3. Fast Track Judgment (This is the only official decision point)

根据用户描述的线索先读一下相关代码（用 Grep / Read 定位），判断能不能一眼确定根因：

能——根因明确（能给出
```
{文件}:{行号}
```
）、修复改动小（1-2 处）、无跨模块影响风险 → 告诉用户："我已经看到问题所在，可以走快速通道：直接告知根因和修复方案，你确认后我立刻修，修完你验证，然后只写一份
```
{slug}-fix-note.md
```
。" 用户同意后触发
```
cs-issue-fix
```
（快速通道模式）。
不能——根因有多个候选 / 不确定 / 需要更多复现信息 → 继续走下面的标准路径，做完整问题报告。进入标准路径后默认不再二次改判。

Based on the clues from the user's description, first review the relevant code (locate using Grep / Read) to determine if the root cause can be identified at a glance:

Yes — Clear root cause (can provide
```
{file}:{line number}
```
), minor fix changes (1-2 places), no cross-module impact risk → Inform the user: "I have identified the issue. We can take the fast track: I will directly inform you of the root cause and fix plan. After your confirmation, I will immediately fix it, you verify the fix, and then only a
```
{slug}-fix-note.md
```
needs to be written." Trigger
```
cs-issue-fix
```
(fast track mode) after the user agrees.
No — Multiple candidate root causes / uncertain / need more reproduction information → Proceed with the standard path below to create a complete issue report. No re-judgment will be made by default after entering the standard path.

4. 确定 issue 目录名

4. Determine the issue directory name

跟用户商定 slug，日期前缀用今天的日期（从环境信息查

currentDate

）。目录不存在就创建。快速通道也要建 issue 目录，

{slug}-fix-note.md

放在那里。

Agree on the slug with the user, using today's date as the prefix (retrieve

currentDate

from environment information). Create the directory if it does not exist. An issue directory must also be created for the fast track, and

{slug}-fix-note.md

should be placed there.

必答 5 问

5 Mandatory Questions

按顺序逐个问，不要一次抛 5 个——一次抛多个问题用户大概率只回最容易的，深的就漏了。每个问题做一次模糊度检查，不通过继续追问。

Ask one question at a time in order, do not throw all 5 at once — if multiple questions are asked at once, the user will most likely only answer the easiest ones, and deeper information will be missed. Perform an ambiguity check for each question; if it fails, continue to follow up.

1. 问题是什么？能描述一下你看到的现象吗？

1. What is the issue? Can you describe the phenomenon you observed?

期待具体的异常表现："点击提交按钮后弹出了空白弹窗"比"提交功能有问题"有用一百倍。

模糊信号："有时候会出错"、"感觉不对" → 追问"具体什么时候"、"具体什么不对"。

红线：不要让用户描述根因。出现"应该是因为 XXX"、"可能是 YYY 导致的"——记现象，根因留给阶段 2。

Expect specific abnormal behaviors: "A blank pop-up appears after clicking the submit button" is a hundred times more useful than "There's a problem with the submission function".

Ambiguous signals: "Sometimes it errors"、"It feels wrong" → Follow up with "When exactly does this happen?"、"What exactly is wrong?".

Red line: Do not let the user describe the root cause. If the user says "It should be because of XXX"、"Maybe YYY caused it" — record the phenomenon, leave the root cause to Stage 2.

2. 怎么复现？

2. How to reproduce it?

期待一组最小复现步骤。例如：

进入 XX 页面
输入 YY 内容
点击 ZZ 按钮
看到问题现象

模糊信号："不稳定复现"、"有时候能有时候不能" → 追问复现频率和条件差异（"什么情况下能复现"）。如果确实不稳定，写明已知触发条件和复现率。

"无法复现"也是有效回答——写明"目前无法稳定复现，只在 X 情况下观察到一次"，别勉强凑步骤。

Expect a set of minimal reproduction steps. For example:

Go to the XX page
Enter YY content
Click the ZZ button
Observe the issue phenomenon

Ambiguous signals: "Unstable reproduction"、"Sometimes it works, sometimes it doesn't" → Follow up on the reproduction frequency and conditional differences ("Under what conditions can it be reproduced?"). If it is indeed unstable, specify the known trigger conditions and reproduction rate.

"Cannot reproduce" is also a valid answer — specify "Currently cannot stably reproduce, only observed once under condition X", do not force to create steps.

3. 期望行为 vs 实际行为

3. Expected Behavior vs Actual Behavior

期待两句话：

期望：我以为做了 A 之后应该发生 B
实际：但实际发生的是 C

不要合并成一句。期望和实际显式分开写，审查者才能快速判断问题边界——合在一句"按钮没正常工作"里，分析的人不知道你期望的"正常"长什么样。

Expect two sentences:

Expected: I thought after doing A, B should happen
Actual: But what actually happened was C

Do not combine into one sentence. Explicitly separate expected and actual behaviors so that reviewers can quickly judge the issue boundary — if combined into "The button isn't working properly", analysts won't know what you consider "proper".

4. 环境信息

4. Environment Information

最低要采集：在哪个模块 / 功能区域发现的、相关文件或函数（如果用户知道）。

可选但有价值：操作系统、浏览器版本、运行环境（dev / prod）、最近有没有改过相关代码。

如果用户说"我不知道在哪个文件"——没关系，写"待定"，阶段 2 分析时会查。

At minimum, collect: Which module/functional area the issue was found in、Relevant files or functions (if the user knows).

Optional but valuable: Operating system, browser version, runtime environment (dev / prod), whether relevant code has been modified recently.

If the user says "I don't know which file" — it's okay, write "To be determined", it will be checked during Stage 2 analysis.

5. 严重程度与优先级

5. Severity and Priority

参考标准（给用户选）：

P0 - 阻塞：核心功能完全失效，影响所有用户，必须立刻修
P1 - 严重：核心功能受损，有绕过方法，需要尽快修
P2 - 中等：非核心功能受损或影响少数用户，计划内修
P3 - 轻微：UI 瑕疵、边界情况、有更好的实现，按空闲修

用户不确定就帮他根据前几问的描述推荐一个，但让用户最终拍板。

Reference standards (for the user to choose):

P0 - Blocking: Core function completely fails, affecting all users, must be fixed immediately
P1 - Critical: Core function is impaired, there is a workaround, needs to be fixed as soon as possible
P2 - Medium: Non-core function is impaired or affects a small number of users, fixed within the plan
P3 - Minor: UI flaws, edge cases, better implementation exists, fixed when available

If the user is unsure, recommend one based on the descriptions from previous questions, but let the user make the final decision.

问题报告模板

Issue Report Template

回答完后写进文件（路径见

cs-issue

的"文件放哪儿"节）：

markdown

---
doc_type: issue-report
issue: {issue 目录名}
status: draft
severity: P0 | P1 | P2 | P3
summary: {问题现象一句话}
tags: []
---

After getting all answers, write into the file (see the "Where to place files" section of

cs-issue

for the path):

markdown

---
doc_type: issue-report
issue: {issue directory name}
status: draft
severity: P0 | P1 | P2 | P3
summary: {one-sentence issue phenomenon}
tags: []
---

{问题简述} Issue Report

{Brief Issue Description} Issue Report

1. 问题现象

1. Issue Phenomenon

{用户描述的具体异常表现，纯现象描述，不含根因推测}

{Specific abnormal behavior described by the user, pure phenomenon description without root cause speculation}

2. 复现步骤

2. Reproduction Steps

{步骤 1}
{步骤 2}
{步骤 3}
观察到：{问题现象}

复现频率：{稳定复现 / 概率复现（约 X%） / 暂无法稳定复现}

{Step 1}
{Step 2}
{Step 3}
Observed: {Issue phenomenon}

Reproduction frequency: {Stable reproduction / Probabilistic reproduction (approx. X%) / Currently unable to stably reproduce}

3. 期望 vs 实际

3. Expected vs Actual

期望行为：{做了 A 应该发生 B}

实际行为：{但实际发生了 C}

Expected Behavior: {After doing A, B should happen}

Actual Behavior: {But what actually happened was C}

4. 环境信息

4. Environment Information

涉及模块 / 功能：{模块名或功能描述}
相关文件 / 函数：{已知文件:行号，或"待定"}
运行环境：{dev / staging / prod / 不确定}
其他上下文：{OS、浏览器、最近改动等，没有就写"无"}

Involved module/function: {Module name or function description}
Relevant files/functions: {Known file:line number, or "To be determined"}
Runtime environment: {dev / staging / prod / Uncertain}
Other context: {OS, browser, recent changes, etc. Write "None" if none}

5. 严重程度

5. Severity

{P0 / P1 / P2 / P3} — {一句话说明理由}

{P0 / P1 / P2 / P3} — {One-sentence reason}

备注

Notes

{可选：用户额外补充的上下文、截图描述、日志片段等}

---

{Optional: Additional context provided by the user, screenshot descriptions, log snippets, etc.}

---

退出条件

Exit Criteria

写完文件后跟用户做一次"出阶段 1"确认：

YAML frontmatter 存在，
```
doc_type=issue-report
```
、
```
issue
```
跟当前 issue 目录一致、
```
severity
```
和
```
summary
```
非空、
```
tags
```
至少 1 个
5 个问题都有具体答案，没有"待定"（环境中的相关文件可以是"待定"）
问题现象是纯现象描述，没混入根因推测
期望 vs 实际显式分开写
复现步骤可执行（哪怕是"暂无法稳定复现"也有说明）
用户明确说"report 可以了，进下一步"
用户确认后，frontmatter 的
```
status
```
已改成
```
confirmed
```

After writing the file, confirm with the user to "exit Stage 1":

YAML frontmatter exists,
```
doc_type=issue-report
```
,
```
issue
```
matches the current issue directory,
```
severity
```
and
```
summary
```
are not empty,
```
tags
```
has at least one entry
All 5 questions have specific answers, no "To be determined" (except for relevant files in environment info which can be "To be determined")
Issue phenomenon is a pure description of the phenomenon, with no root cause speculation mixed in
Expected vs Actual behaviors are explicitly separated
Reproduction steps are executable (even if "currently unable to stably reproduce" is stated with explanations)
The user explicitly says "The report is ready, proceed to the next step"
After user confirmation, the
```
status
```
in the frontmatter has been changed to
```
confirmed
```

退出后

After Exit

告诉用户："问题报告已就绪。下一步是阶段 2：根因分析。可以触发

cs-issue-analyze

技能开始分析。"

别自己顺手开始分析根因——阶段间的人工 checkpoint 是工作流的硬约束。

Inform the user: "The issue report is ready. The next step is Stage 2: Root Cause Analysis. You can trigger the

cs-issue-analyze

skill to start the analysis."

Do not start analyzing the root cause on your own — manual checkpoints between stages are hard constraints of the workflow.

容易踩的坑

Common Pitfalls

用户说"可能是 XX 组件的问题"，你顺着聊起根因——错，那是阶段 2，现在只问"看到什么现象"
复现步骤太模糊（"在用户界面操作一下"）就放行——逼出可执行的步骤
期望行为和实际行为混在一段话里——必须显式分开
严重程度留空——给个默认值或写"无"，但别空着
一口气把 5 个问题列成清单丢给用户填——逐题对话，否则深的全漏

When the user says "Maybe it's a problem with the XX component", you start discussing the root cause — Wrong, that's Stage 2's job; only ask about "what phenomenon you observed" now
Allowing overly vague reproduction steps (e.g., "Operate on the user interface") — Force executable steps out
Mixing expected and actual behaviors in one paragraph — Must be explicitly separated
Leaving severity blank — Provide a default value or write "None", but do not leave it empty
Throwing all 5 questions as a list to the user at once — Ask one question at a time in conversation, otherwise deep information will be missed