easysdd-issue-analyze

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

easysdd-issue-analyze

到这一步用户已经把问题描述清楚了，你的活是通过实际读代码找到根因——不是在脑子里推断、不是在报告基础上猜。读代码是这一阶段的核心动作，跳过它写出来的分析没价值。

分析完不是直接动手——给用户看 2-3 种修复方案，让 TA 选。原因：根因往往有多种修法，影响面、副作用、改动范围各不相同，这是用户该拍板的事，不是 AI 该替 TA 决定的。

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

At this point, the user has clearly described the issue. Your task is to identify the root cause by actually reading the code — not inferring in your mind, not guessing based on the report. Reading code is the core action of this phase; analysis written without skipping this step is valueless.

After analysis, don't start fixing directly — provide the user with 2-3 repair plans and let them choose. Reason: There are often multiple ways to fix the root cause, with varying impact scopes, side effects, and modification ranges. This is something the user should decide, not something the AI should decide for them.

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. 问题报告存在且已确认

1. Issue Report Exists and Confirmed

读 issue 目录下的

{slug}-report.md

，确认 frontmatter 有

doc_type=issue-report

且

status=confirmed

，5 节都有内容。不完整或 status 不是 confirmed 就先回

easysdd-issue-report

。

如果

easysdd-issue-report

已判定走标准路径，本阶段按标准路径完成根因分析，不再二次改判快速通道。

Read

{slug}-report.md

in the issue directory, confirm that the frontmatter has

doc_type=issue-report

and

status=confirmed

, and all 5 sections have content. If it's incomplete or the status is not confirmed, return to

easysdd-issue-report

first.

easysdd-issue-report

has determined to follow the standard path, complete the root cause analysis according to the standard path in this phase, and do not re-judge the fast track for the second time.

2. 断点恢复

2. Breakpoint Recovery

{slug}-analysis.md

已存在的话检查 5 节哪些已有实质内容：

全部填满但
```
status=draft
```
→ 上次写完了还没和用户对齐，跳到 checkpoint
部分填写 → 汇报"上次分析做到第 X 步，我从第 Y 步继续"，从缺失节开始补做

{slug}-analysis.md

already exists, check which of the 5 sections have substantive content:

All filled but
```
status=draft
```
→ Last time it was written but not aligned with the user, jump to checkpoint
Partially filled → Report "Last analysis reached step X, I will continue from step Y", and fill in the missing sections starting from there

3. 把上下文读全

3. Read the Full Context

问题报告全文
```
AGENTS.md
```
报告里提到的相关文件（用 Glob / Grep 找，别只凭 report 里的描述）
```
easysdd/architecture/DESIGN.md
```
（如果涉及跨模块问题）
归档检索（按需）——只在问题涉及的模块曾有归档记录时才搜（目录为空或与问题无关就跳过）。统一搜
```
easysdd/compound/
```
，按需用
```
doc_type
```
过滤：
- 一把搜：
```
python easysdd/tools/search-yaml.py --dir easysdd/compound --query "{issue 关键词}"
```
- 只看技巧：追加
```
--filter doc_type=trick --filter status=active
```
  —— 命中则在分析开头标注引用
- 只看探索：追加
```
--filter doc_type=explore
```
  —— 命中则标注历史探索结论
- 只看经验（pitfall）：追加
```
--filter doc_type=learning --filter track=pitfall
```
  —— 命中则标注历史 pitfall

Full issue report
```
AGENTS.md
```
Related files mentioned in the report (find using Glob / Grep, don't rely only on the description in the report)
```
easysdd/architecture/DESIGN.md
```
(if cross-module issues are involved)
Archive Retrieval (On Demand) — Only search when the module involved in the issue has archive records (skip if the directory is empty or irrelevant to the issue). Search uniformly in
```
easysdd/compound/
```
, filter by
```
doc_type
```
as needed:
- Full search:
```
python easysdd/tools/search-yaml.py --dir easysdd/compound --query "{issue keywords}"
```
- Only view tricks: Append
```
--filter doc_type=trick --filter status=active
```
  — If hit, mark the reference at the beginning of the analysis
- Only view explorations: Append
```
--filter doc_type=explore
```
  — If hit, mark historical exploration conclusions
- Only view pitfalls (learning): Append
```
--filter doc_type=learning --filter track=pitfall
```
  — If hit, mark historical pitfalls

分析的五步

Five Steps of Analysis

每一步都要真正读代码，不要靠推测。

Each step requires actually reading the code, do not rely on speculation.

步骤 1：定位问题代码

Step 1: Locate the Problem Code

根据报告里的"涉及模块 / 功能"和"复现步骤"，用 Grep / Glob 找相关代码：

搜报告里提到的函数名、类名、文件名
沿调用链追溯（从用户触发的入口往下找）
重点关注：条件分支、边界值处理、状态更新、异步逻辑、数据流转

记下定位到的关键位置：

{文件}:{行号} — {说明这里干什么}

。

Based on the "Involved Modules / Functions" and "Reproduction Steps" in the report, find relevant code using Grep / Glob:

Search for function names, class names, file names mentioned in the report
Trace along the call chain (from the entry triggered by the user downwards)
Focus on: Conditional branches, boundary value processing, state updates, asynchronous logic, data flow

Record the key locations identified:

{File}:{Line Number} — {Description of what this does}

步骤 2：还原失败路径

Step 2: Restore the Failure Path

对照复现步骤，在脑子里（或实际跑一遍）把代码执行路径走一遍：

用户触发了什么 → 调了哪个函数 → 数据怎么流 → 哪里分叉走错了
描述"正确路径"和"失败路径"的分叉点
分叉点 = 根因候选

Compare the reproduction steps, walk through the code execution path in your mind (or run it actually):

What did the user trigger → Which function was called → How did the data flow → Where did it branch incorrectly
Describe the fork point between the "correct path" and "failure path"
Fork point = Root cause candidate

步骤 3：确认根因

Step 3: Confirm the Root Cause

单一根因 vs 多个根因：有多个根因就一一列出，说明主次
根因分类（帮助后续定位修复范围）：
- 逻辑错误：条件判断有误、边界值处理缺失
- 状态污染：某处副作用影响了后续流程
- 数据格式：输入 / 输出格式假设不符合实际
- 并发 / 竞态：异步顺序或共享状态问题
- 配置 / 环境：依赖了某个未稳定的配置项
- 缺少防御：没处理 null / undefined / 空列表等边界

Single root cause vs multiple root causes: If there are multiple root causes, list them one by one and explain their priority
Root cause classification (helps locate the repair scope later):
- Logic Error: Incorrect conditional judgment, missing boundary value processing
- State Pollution: Side effects somewhere affect subsequent processes
- Data Format: Input / output format assumptions do not match reality
- Concurrency / Race Condition: Asynchronous order or shared state issues
- Configuration / Environment: Depends on an unstable configuration item
- Missing Defense: No handling of boundaries such as null / undefined / empty lists

步骤 4：影响面评估

Step 4: Impact Assessment

影响范围：只影响报告描述的场景，还是会影响更多场景？
潜在受害者：哪些其他功能 / 模块可能被同一根因波及？
数据完整性：这个 bug 会不会导致数据损坏或状态不一致？
严重程度复核：和报告里的 P0/P1/P2/P3 比较，是否需要调整？

为什么要复核严重程度？report 阶段用户给的是基于现象的判断，分析后你看到了影响面——往往会发现问题比看上去严重（一个看似 P2 的小 bug 实际影响了核心数据的完整性）或没那么严重。

Impact Scope: Only affects the scenario described in the report, or affects more scenarios?
Potential Victims: Which other functions / modules may be affected by the same root cause?
Data Integrity: Will this bug cause data corruption or state inconsistency?
Severity Review: Compare with P0/P1/P2/P3 in the report, does it need adjustment?

Why review severity? The user's judgment in the report phase is based on phenomena; after analysis, you see the impact scope — often you will find that the problem is more serious than it seems (a seemingly P2 small bug actually affects the integrity of core data) or less serious.

步骤 5：修复方案选项

Step 5: Repair Plan Options

列 2-3 种修复方向，每种说明：

做什么：改哪里、怎么改（代码层面描述，不需要写代码）
优点：为什么这么改好
缺点 / 风险：改这里可能带来什么副作用
影响面：改动会触碰哪些文件、会不会影响其他功能

推荐方案：在 2-3 种里挑一种说明推荐理由（通常是：改动范围最小 + 根因最直接 + 副作用最少）。

List 2-3 repair directions, each explaining:

What to do: Where to modify, how to modify (describe at the code level, no need to write code)
Advantages: Why this modification is good
Disadvantages / Risks: What side effects may be brought by modifying here
Impact Scope: Which files will be touched by the modification, will it affect other functions

Recommended Plan: Pick one of the 2-3 options and explain the recommendation reason (usually: smallest modification scope + most direct root cause + least side effects).

根因分析模板

Root Cause Analysis Template

分析完写进文件（路径见

easysdd-issue

的"文件放哪儿"节）：

markdown

---
doc_type: issue-analysis
issue: {issue 目录名}
status: draft
root_cause_type: logic | state-pollution | data-format | concurrency | config | missing-guard
related: [{slug-report.md 相对路径}]
tags: []
---

After analysis, write into the file (see the "Where to put files" section of

easysdd-issue

for the path):

markdown

---
doc_type: issue-analysis
issue: {issue directory name}
status: draft
root_cause_type: logic | state-pollution | data-format | concurrency | config | missing-guard
related: [{relative path of slug-report.md}]
tags: []
---

{问题简述} 根因分析

Root Cause Analysis of {Issue Brief}

1. 问题定位

1. Issue Location

关键位置	说明
`{文件}:{行号}`	{这里干什么，为什么有问题}
`{文件}:{行号}`	...

Key Location	Description
`{File}:{Line Number}`	{What this does, why there is a problem}
`{File}:{Line Number}`	...

2. 失败路径还原

2. Failure Path Restoration

正常路径： {用户做 A → 调用 B → 数据经过 C → 结果 D（符合期望）}

失败路径： {用户做 A → 调用 B → 在 C 处因为 E 走了错误分支 → 结果 F（不符合期望）}

分叉点：

{文件}:{行号}

— {为什么这里走错了}

Normal Path: {User does A → calls B → data passes through C → result D (meets expectation)}

Failure Path: {User does A → calls B → takes wrong branch at C because of E → result F (does not meet expectation)}

Fork Point:

{File}:{Line Number}

— {Why it went wrong here}

3. 根因

3. Root Cause

根因类型：{逻辑错误 / 状态污染 / 数据格式 / 并发竞态 / 配置环境 / 缺少防御}

根因描述： {一段话说清楚为什么会发生这个问题，要能让没看过代码的人理解}

是否有多个根因：{是 / 否。如果是，列出并说明主次}

Root Cause Type: {Logic Error / State Pollution / Data Format / Concurrency Race Condition / Configuration Environment / Missing Defense}

Root Cause Description: {A paragraph explaining why this problem occurs, which should be understandable to someone who hasn't seen the code}

Multiple Root Causes: {Yes / No. If yes, list them and explain their priority}

4. 影响面

4. Impact Scope

影响范围：{只影响报告场景 / 还会影响 X、Y、Z 场景}
潜在受害模块：{列出可能被波及的其他模块或功能}
数据完整性风险：{有 / 无。有的话说明风险内容}
严重程度复核：{维持 P? / 调整为 P?，理由}

Impact Scope: {Only affects report scenario / Also affects X, Y, Z scenarios}
Potential Victim Modules: {List other modules or functions that may be affected}
Data Integrity Risk: {Yes / No. If yes, explain the risk content}
Severity Review: {Maintain P? / Adjust to P?, reason}

5. 修复方案

5. Repair Plans

方案 A：{方案名}

Plan A: {Plan Name}

做什么：{改哪里、怎么改}
优点：{...}
缺点 / 风险：{...}
影响面：{会动哪些文件，会不会影响其他功能}

What to do: {Where to modify, how to modify}
Advantages: {...}
Disadvantages / Risks: {...}
Impact Scope: {Which files will be modified, will it affect other functions}

方案 B：{方案名}

Plan B: {Plan Name}

做什么：{...}
...

What to do: {...}
...

Recommended Plan

推荐方案 {A / B}，理由：{改动范围最小 / 根因最直接 / 副作用最少 + 具体说明}

---

Recommended Plan {A / B}, Reason: {Smallest modification scope / Most direct root cause / Least side effects + specific explanation}

---

checkpoint：和用户对齐

Checkpoint: Align with User

写完

{slug}-analysis.md

后别直接开始修。做一次对齐：

把"根因"和"推荐方案"口头总结给用户（不要让用户去读整份文件——TA 已经在等结论了）
问用户："根因判断是否准确？推荐的修复方案你是否认可，还是想选别的方向？"
等用户明确确认方案后才触发阶段 3

After writing

{slug}-analysis.md

, do not start fixing directly. Conduct an alignment:

Verbally summarize the "root cause" and "recommended plan" to the user (don't let the user read the entire file — TA is already waiting for the conclusion)
Ask the user: "Is the root cause judgment accurate? Do you agree with the recommended repair plan, or do you want to choose another direction?"
Only trigger Phase 3 after the user explicitly confirms the plan

退出条件

Exit Conditions

YAML frontmatter 存在，
```
doc_type=issue-analysis
```
、
```
issue
```
跟当前 issue 目录一致
根因分析 5 节都填完
定位到了具体的代码位置（
```
{文件}:{行号}
```
粒度）
失败路径还原清晰
影响面评估完成
至少列出 2 种修复方案并给出推荐
用户明确确认方案："分析准确，用方案 X 修"
用户确认后，frontmatter 的
```
status
```
已改成
```
confirmed
```

YAML frontmatter exists,
```
doc_type=issue-analysis
```
,
```
issue
```
matches the current issue directory
All 5 sections of the root cause analysis are filled
Specific code locations are located (granularity of
```
{File}:{Line Number}
```
)
Failure path restoration is clear
Impact assessment is completed
At least 2 repair plans are listed and a recommendation is given
User explicitly confirms the plan: "Analysis is accurate, fix with Plan X"
After user confirmation,
```
status
```
in frontmatter is changed to
```
confirmed
```

退出后

After Exit

告诉用户："根因分析已就绪，方案已确认。下一步是阶段 3：修复验证。可以触发

easysdd-issue-fix

技能开始修复。"

别自己顺手开始改代码——理由跟其他阶段一样：跨阶段无停顿地往下跑会让用户来不及把关。

Tell the user: "Root cause analysis is ready, and the plan has been confirmed. The next step is Phase 3: Repair Verification. You can trigger the

easysdd-issue-fix

skill to start the repair."

Don't start modifying code yourself — the reason is the same as other phases: running continuously across phases without pausing will leave the user no time to review.

容易踩的坑

Common Pitfalls

根因写"可能是某处的问题"——必须定位到具体文件:行号
没读代码就靠问题描述推断根因——一定要实际 Grep / Read
只列一种修复方案——至少给用户两种选择
分析完直接开始改代码——必须等用户确认方案
影响面写"可能影响其他功能"——要具体说是哪些功能 / 模块
严重程度复核总是"维持原级别"——认真看影响面，确实升级的要改

Writing root cause as "may be a problem somewhere" — must locate to specific file:line number
Inferring root cause from issue description without reading code — must actually use Grep / Read
Listing only one repair plan — provide at least two options for the user
Starting to modify code directly after analysis — must wait for user confirmation of the plan
Writing impact scope as "may affect other functions" — specify which functions / modules exactly
Always "maintaining the original level" in severity review — carefully check the impact scope, and modify if it really needs to be upgraded