easysdd-issue-report
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
for shared paths and naming conventions.
Startup Checks
1. Confirm it's a bug, not a new feature request
If the user describes "want to add an X feature", tell them to follow the
workflow (routed to the appropriate phase by the root skill).
2. Check if there's a related issue directory
Glob the subdirectories under
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. Fast Track Judgment (This is the only official decision point)
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 ), 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 ." After the user agrees, trigger (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. Determine the issue directory name
Agree on the slug with the user, use today's date as the date prefix (retrieve
from environment information). Create the directory if it doesn't exist. The fast track also requires an issue directory, and
will be placed there.
5 Mandatory Questions
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. What's the problem? Can you describe the phenomenon you saw?
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. How to reproduce it?
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. Expected Behavior vs Actual Behavior
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. Environment Information
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. Severity and Priority
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
After getting the answers, write them into the file (path see the "Where to put files" section of
):
markdown
---
doc_type: issue-report
issue: {issue 目录名}
status: draft
severity: P0 | P1 | P2 | P3
summary: {问题现象一句话}
tags: []
---
# {问题简述} Issue Report
## 1. 问题现象
{用户描述的具体异常表现，纯现象描述，不含根因推测}
## 2. 复现步骤
1. {步骤 1}
2. {步骤 2}
3. {步骤 3}
4. 观察到：{问题现象}
复现频率：{稳定复现 / 概率复现（约 X%） / 暂无法稳定复现}
## 3. 期望 vs 实际
**期望行为**：{做了 A 应该发生 B}
**实际行为**：{但实际发生了 C}
## 4. 环境信息
- 涉及模块 / 功能：{模块名或功能描述}
- 相关文件 / 函数：{已知文件:行号，或"待定"}
- 运行环境：{dev / staging / prod / 不确定}
- 其他上下文：{OS、浏览器、最近改动等，没有就写"无"}
## 5. 严重程度
**{P0 / P1 / P2 / P3}** — {一句话说明理由}
## 备注
{可选：用户额外补充的上下文、截图描述、日志片段等}
Exit Conditions
After writing the file, confirm "exit Phase 1" with the user:
After Exit
Tell the user: "The issue report is ready. The next step is Phase 2: Root Cause Analysis. You can trigger the
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
- 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