easysdd-issue-analyze

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. Issue Report Exists and Confirmed

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. Breakpoint Recovery

{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. Read the Full Context

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.

Step 1: Locate the Problem Code

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}

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

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 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

Step 4: Impact Assessment

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.

Step 5: Repair Plan Options

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

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. Issue Location

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

## 2. Failure Path Restoration

**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. 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. Impact Scope

- **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. Repair Plans

### 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}

### Plan B: {Plan Name}

- **What to do**: {...}
- ...

### Recommended Plan

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

Checkpoint: Align with User

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 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

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

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

easysdd-issue-analyze

NPX Install

Tags

SKILL.md Content (Chinese)

easysdd-issue-analyze

Startup Checks

1. Issue Report Exists and Confirmed

2. Breakpoint Recovery

3. Read the Full Context

Five Steps of Analysis

Step 1: Locate the Problem Code

Step 2: Restore the Failure Path

Step 3: Confirm the Root Cause

Step 4: Impact Assessment

Step 5: Repair Plan Options

Root Cause Analysis Template

Checkpoint: Align with User

Exit Conditions

After Exit

Common Pitfalls