cs-issue-analyze

cs-issue-analyze

Required reading before starting

Before making any judgment or taking any action, first run the CodeStable preflight: read .codestable/attention.md; if missing, first cs-onboard; do not read external AI entry points as a substitute (see .codestable/reference/execution-conventions.md）。

The user has already described the problem clearly; your job isto find the root cause by actually reading the code—not to infer it in your head, and not to guess based on the report. Reading code is the core action; an analysis written by skipping it has no value.

After the analysis, do not act directly—show the user 2-3 fix options and let them choose. Reason: a root cause often has multiple fixes, with different impact / side effects / scope of change, and this is something the user should decide.

For shared paths and naming conventions, see .codestable/reference/shared-conventions.md Section 0 and cs-issue "Where files go".

Startup check

The issue report exists and has been confirmed—read {slug}-report.md, confirm doc_type=issue-report and status=confirmed, all 5 sections have content. If incomplete / status incorrect → go back to cs-issue-report。cs-issue-report If it has already been judged to follow the standard path, follow the standard path; do not re-judge
Resume from breakpoint——{slug}-analysis.md If it already exists, check which of the 5 sections are filled:
- All filled but status=draft → skip to checkpoint
- Partially filled → report "last time reached step X, continue from step Y"
Read the full context：
- Full issue report + .codestable/attention.md
- related files mentioned in the report (use Glob / Grep to find them, don't rely only on the description)
- Scan .codestable/ globally——Glob .codestable/ to find available inputs, and use them as needed:requirements/CONTEXT.md + requirements/adrs/(read when domain terminology / decision-making is involved),compound/（grep -r search historical records by keyword; if there is a hit, note the citation at the beginning of the analysis),requirements/{slug}.md(read when capability boundaries are involved)

The five steps of analysis

Every step musttruly read the codeDo not rely on speculation.

Step 1: Locate the problematic code

Based on the report's "involved modules / reproduction steps", use Grep / Glob to find: search function names / class names / file names; trace along the call chain (start from the user entry point and go downward); focus on conditional branches / boundary values / state updates / async / data flow.

Record key locations:{文件}:{行号} — {这里干什么}。

Step 2: Reconstruct the failure path

Walk through the code execution path against the reproduction steps: what the user triggers → which function is called → how data flows → where it branches incorrectly. Describe the branch point between the "normal path" and the "failure path".Branch point = root cause candidate。

Step 3: Confirm the root cause

Single vs multiple root causes; for multiple root causes, list primary and secondary.

Root cause classification：

Logic error (conditional judgment / missing boundary value)
State pollution (side effects affect subsequent flow)
Data format (input / output format assumptions do not match reality)
Concurrency / race condition (async order / shared state)
Configuration / environment (dependence on unstable configuration)
Missing defense (does not handle null / undefined / empty list and other boundaries)

Step 4: Impact assessment

Impact scope: does it affect only the reported scenario, or more scenarios?
Potential victims: Which other features / modules may be affected by the same root cause?
Data integrity: Could it cause data corruption or state inconsistency?
Severity re-review: Compared with the reported P0/P1/P2/P3, does it need to be adjusted?

Why re-review: what the report stage gives is a judgment based on symptoms; after analysis you see the scope of impact—often the problem turns out to be more serious or less serious than it appeared.

Step 5: Fix option(s)

List 2-3 directions, and explain each one: what to do (where to change, how to change) / pros / cons and risks / scope of impact (which files will be touched, will other features be affected).

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

Root cause analysis template

---
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 writingDon't start fixing directly：

Summarize the "root cause" and "recommended option" verbally for the user (don't make the user read the whole file—they are waiting for a conclusion)
Ask "Is the root cause judgment accurate? Do you approve the recommended option, or do you want to choose another one?"
Only after the user explicitly confirms the option is stage 3 triggered

Exit conditions

frontmatter exists (doc_type=issue-analysis / issue consistent)
All 5 sections are filled in
Located to a specific code location ({文件}:{行号}）
Failure path reproduction is clear
Impact scope assessment completed
At least 2 fix options + recommendation
The user explicitly confirms "the analysis is accurate, fix it with option X"
frontmatter status: confirmed

After exiting

Tell the user: "Root cause analysis is ready, the option has been confirmed. Next is stage 3 fix verification, trigger cs-issue-fix。"

Don't just go ahead and change the code yourself—running straight through across stages without pausing leaves the user no time to check.

Common pitfalls

Writing the root cause as "may be a problem somewhere"—must locate it to file:line
Inferring from the problem description without reading the code—be sure to actually Grep / Read
Listing only one fix option—at least two
Starting to change the code directly after analysis—must wait for user confirmation
Writing the impact scope as "may affect other features"—must specifically say which ones
The severity re-review is always "maintain"—look carefully at the impact scope, and change it if it should be upgraded