SuperAPI AI Directory
Partner中文AI newsFavorites
Skillseasysdd-issue-analyze

easysdd-issue-analyze

Coding & development

View repository

Updated 10-15 19:51

About this skill

easysdd-issue-analyze

By this point the user has described the problem clearly, and your job is tofind the root cause by actually reading the code—not by inferring in your head, not by guessing based on the report. Reading code is the core action of this stage; analysis written without it has no value.

After analysis, don't jump straight into action—show the user 2-3 fix options and let them choose. Reason: a root cause often has multiple fixes, with different impact, side effects, and scope of change, and this is something the user should decide, not something the AI should decide for them.

For shared paths and naming conventions, see easysdd/reference/shared-conventions.md section 0 and easysdd-issue 's "where files go" section.

Startup check

1. The issue report exists and has been confirmed

Read the {slug}-report.mdunder the issue directory, and confirm that the frontmatter has doc_type=issue-report and status=confirmed, and that all 5 sections have content. If it is incomplete or status is not confirmed, go back to easysdd-issue-report。

If easysdd-issue-report has already been determined to follow the standard path, complete the root cause analysis according to the standard path in this stage, and do not re-judge it into the fast track a second time.

2. Breakpoint recovery

{slug}-analysis.md If already exists, check which of the 5 sections already have substantive content:

  • All filled in but status=draft → last time it was written but not yet aligned with the user; skip to checkpoint
  • Partially filled → report "last analysis reached step X, I will continue from step Y," and resume from the missing section

3. Read the full context

  • Full text of the issue report
  • AGENTS.md
  • Related files mentioned in the report (use Glob / Grep to find them, don't rely only on the description in the report)
  • easysdd/architecture/DESIGN.md(if it involves cross-module issues)
  • Archive search (as needed)—search only when the module involved in the issue has archive records (if the directory is empty or unrelated to the issue, skip it). Search uniformly easysdd/compound/, and filter as needed with doc_type :
    • Search all at once:python easysdd/tools/search-yaml.py --dir easysdd/compound --query "{issue 关键词}"
    • Only look at techniques: append --filter doc_type=trick --filter status=active — if there is a hit, annotate the reference at the beginning of the analysis
    • Only look at exploration: append --filter doc_type=explore — if there is a hit, annotate the historical exploration conclusion
    • Only look at experience (pitfall): append --filter doc_type=learning --filter track=pitfall — if there is a hit, annotate the historical pitfall

The five steps of analysis

Every step mustactually read the code, do not rely on speculation.

Step 1: Locate the problem code

Based on the "involved module / feature" and "reproduction steps" in the report, use Grep / Glob to find the relevant code:

  • Search for the function names, class names, and file names mentioned in the report
  • Trace along the call chain (starting from the entry point triggered by the user and working downward)
  • Focus on: conditional branches, boundary value handling, state updates, asynchronous logic, data flow

Note down the key locations you have identified:{文件}:{行号} — {说明这里干什么}。

Step 2: Reconstruct the failure path

Against the reproduction steps, walk through the code execution path in your head (or actually run it once):

  • What did the user trigger → which function was called → how did the data flow → where did it branch off and go wrong
  • Describe the branch point between the "correct path" and the "failure path"
  • Branch point = root cause candidate

Step 3: Confirm the root cause

  • Single root cause vs multiple root causes: if there are multiple root causes, list them one by one and explain which is primary and which is secondary
  • Root cause classification (helps determine the scope of subsequent fixes):
    • Logic error: incorrect conditional judgment, missing boundary value handling
    • State pollution: a side effect somewhere affected subsequent flow
    • Data format: input/output format assumptions do not match reality
    • Concurrency / race condition: asynchronous ordering or shared state issues
    • Configuration / environment: depends on an unstable configuration item
    • Missing defenses: null / undefined / empty list and other boundaries are not handled

Step 4: Impact assessment

  • Impact scope: does it only affect the scenario described in the report, or will it affect more scenarios?
  • Potential victims: which other features/modules may be affected by the same root cause?
  • Data integrity: could this bug cause data corruption or state inconsistency?
  • Severity review: compared with the P0/P1/P2/P3 in the report, does it need to be adjusted?

Why review the severity? In the report stage, what the user gives is a judgment based on symptoms; after analysis you have seen the impact scope—often you will find the problem is more serious than it looked (a small bug that seemed like P2 actually affected the integrity of core data) or less serious.

Step 5: Fix options

List 2-3 fix directions, and for each explain:

  • What to do: where to change, how to change (described at the code level, no need to write code)
  • Pros: why this change is good
  • Cons / risks: what side effects this change may bring
  • Impact scope: which files the change will touch, and whether it will affect other features

Recommended option: choose one from the 2-3 and explain the reason for the recommendation (usually: smallest change scope + most direct root cause + fewest side effects).

Root cause analysis template

After analysis, write it into the file (for the path, see easysdd-issue 's "Where to put the file" section):

---
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: []
---

# {问题简述} 根因分析

## 1. 问题定位

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

## 2. 失败路径还原

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

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

**分叉点**：`{文件}:{行号}` — {为什么这里走错了}

## 3. 根因

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

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

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

## 4. 影响面

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

## 5. 修复方案

### 方案 A：{方案名}

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

### 方案 B：{方案名}

- **做什么**：{...}
- ...

### 推荐方案

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

checkpoint: align with the user

After writing {slug}-analysis.md ,do not start fixing directly. Do one alignment:

  1. Summarize the "root cause" and "recommended option" to the user verbally (do not make the user read the whole file—they are already waiting for the conclusion)
  2. Ask the user: "Is the root cause judgment accurate? Do you approve of the recommended fix, or do you want to choose another direction?"
  3. Only trigger stage 3 after the user clearly confirms the option

Exit conditions

  • YAML frontmatter exists,doc_type=issue-analysis、issue is consistent with the current issue directory
  • All 5 sections of the root cause analysis are filled in
  • A specific code location has been identified ({文件}:{行号} granularity)
  • The failure path is clearly reconstructed
  • The impact assessment is complete
  • List at least 2 fix options and give a recommendation
  • The user explicitly confirms the option: "The analysis is accurate, fix it with option X"
  • After the user confirms, the frontmatter's status has been changed to confirmed

After exiting

Tell the user: "Root cause analysis is ready, and the option has been confirmed. The next step is phase 3: fix verification. You can trigger the easysdd-issue-fix skill to start fixing."

Don't just go ahead and start changing code yourself—the reason is the same as in the other phases: running straight through across phases without pausing gives the user no chance to check.

Common pitfalls

  • Writing the root cause as "it might be a problem somewhere"—you must pinpoint the specific file:line number
  • Inferring the root cause from the problem description without reading the code—be sure to actually Grep / Read
  • Listing only one fix option—give the user at least two choices
  • Starting to change code right after the analysis—you must wait for the user to confirm the option
  • Writing the impact scope as "it may affect other features"—you need to specify which features / modules
  • The severity review always "maintains the original level"—look carefully at the impact scope, and change it if it really should be escalated