easysdd-issue-report

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

easysdd-issue-report

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

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

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

This phase does two things: translate the user's problem into a structured record, and incidentally determine whether the problem should follow the standard path or the fast track.

The core principle for writing the report is: Only record phenomena, not root causes. When the user starts saying "I think it's a problem with the XX component" - note down "User suspects XX component" as a clue, but don't discuss the root cause. Root causes need to be confirmed by actually reading the code in Phase 2, not based on guesses. Reports mixed with root cause guesses will mislead the analysis direction in Phase 2, making analysts go around wrong clues.

See Section 0 of
easysdd/reference/shared-conventions.md
and the "Where to put files" section of
easysdd-issue
for shared paths and naming conventions.

启动检查

Startup Checks

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

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

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

easysdd-feature

工作流（由根技能路由到合适的阶段）。

If the user describes "want to add an X feature", tell them to follow the

easysdd-feature

workflow (routed to the appropriate phase by the root skill).

2. 看有没有相关 issue 目录

2. Check if there's a related issue directory

Glob

easysdd/issues/

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

Glob the subdirectories under

easysdd/issues/

to see if a similar issue has already been recorded. If so, first confirm with the user whether to create a new report or update an existing one.

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

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

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

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

Based on the clues described by the user, first read 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 → Tell the user: "I've identified the issue, we can take the fast track: I'll directly inform you of the root cause and fix solution. After you confirm, I'll fix it immediately, you verify it, and then we only need to write a
```
{slug}-fix-note.md
```
." After the user agrees, trigger
```
easysdd-issue-fix
```
(fast track mode).
No - Multiple candidate root causes / uncertain / need more reproduction information → Continue with the standard path below and complete the full issue report. Once entering the standard path, no secondary judgment will be made by default.

4. 确定 issue 目录名

4. Determine the issue directory name

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

currentDate

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

{slug}-fix-note.md

放在那里。

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

currentDate

from environment information). Create the directory if it doesn't exist. The fast track also requires an issue directory, and

{slug}-fix-note.md

will be placed there.

必答 5 问

5 Mandatory Questions

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

Ask one by one in order, do not throw all 5 questions at once - if you throw multiple questions at once, the user will most likely only answer the easiest ones, and the in-depth ones will be missed. Do a vagueness check for each question; if it fails, continue to follow up.

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

1. What's the problem? Can you describe the phenomenon you saw?

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

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

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

Expect specific abnormal behaviors: "After clicking the submit button, a blank pop-up appeared" is a hundred times more useful than "The submit function has a problem".

Vague signals: "Sometimes it errors"、"Feels wrong" → Follow up with "When exactly?"、"What exactly is wrong?".

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

2. 怎么复现？

2. How to reproduce it?

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

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

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

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

Expect a set of minimal reproduction steps. For example:

Enter the XX page
Input YY content
Click the ZZ button
Observe the problem phenomenon

Vague signals: "Unstable reproduction"、"Sometimes it works, sometimes it doesn't" → Follow up with the reproduction frequency and conditional differences ("Under what circumstances can it be reproduced?"). If it's 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 X circumstances", don't force 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 merge into one sentence. Explicitly separate expected and actual behaviors so reviewers can quickly judge the problem boundary - merging into one sentence like "The button didn't work properly" leaves analysts unaware of what you consider "normal".

4. 环境信息

4. Environment Information

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

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

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

At minimum, collect: Which module / functional area was it found in、Related 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 Phase 2 analysis.

5. 严重程度与优先级

5. Severity and Priority

参考标准（给用户选）：

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

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

Reference standards (let the user choose):

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

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

问题报告模板

Issue Report Template

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

easysdd-issue

的"文件放哪儿"节）：

markdown

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

After getting the answers, write them into the file (path see the "Where to put files" section of

easysdd-issue

markdown

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

{问题简述} Issue Report

1. 问题现象

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

2. 复现步骤

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

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

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

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

3. 期望 vs 实际

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

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

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

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

4. 环境信息

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

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

5. 严重程度

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

备注

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

---

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

---

退出条件

Exit Conditions

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

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

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

YAML frontmatter exists,
```
doc_type=issue-report
```
,
```
issue
```
matches the current issue directory,
```
severity
```
and
```
summary
```
are non-empty,
```
tags
```
has at least 1 entry
All 5 questions have specific answers, no "To be determined" (related files in environment can be "To be determined")
Problem phenomenon is a pure phenomenon description, no root cause speculation mixed in
Expected vs Actual are explicitly separated
Reproduction steps are executable (even "Cannot stably reproduce for now" has an explanation)
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：根因分析。可以触发

easysdd-issue-analyze

技能开始分析。"

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

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

easysdd-issue-analyze

skill to start the analysis."

Don't start analyzing the root cause yourself - the manual checkpoint between phases is a hard constraint of the workflow.

容易踩的坑

Common Pitfalls

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

The user says "Maybe it's a problem with the XX component", and you start discussing the root cause - Wrong, that's Phase 2, now only ask "What phenomenon did you see"
Approve reproduction steps that are too vague ("Operate on the user interface") - Force executable steps
Merge expected and actual behaviors into one paragraph - Must explicitly separate them
Leave severity blank - Provide a default value or write "None", but don't leave it empty
Throw all 5 questions to the user as a checklist at once - Conduct a question-by-question conversation, otherwise all in-depth answers will be missed