---
name: cs-issue-analyze
description: issue 流程阶段 2——读 report + 读代码定位根因、评估风险，给用户 2-3 个修复方案让 TA 拍板。这一步不改代码。触发：用户说"分析这个 bug"、"找根因"、"定位问题"，且已有 {slug}-report.md。
---

# cs-issue-analyze

## 启动必读

开始任何判断或动作前，先读取 `.codestable/attention.md`；缺失则视为骨架不完整，提示先补齐或运行 `cs-onboard`，不要回退到外部 AI 入口文件。

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

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

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

---

## 启动检查

1. **问题报告存在且已确认**——读 `{slug}-report.md`，确认 `doc_type=issue-report` 且 `status=confirmed`，5 节都有内容。不完整 / 状态不对 → 回 `cs-issue-report`。`cs-issue-report` 已判走标准路径就按标准路径走，不二次改判
2. **断点恢复**——`{slug}-analysis.md` 已存在则检查 5 节哪些已填：
   - 全部填满但 `status=draft` → 跳到 checkpoint
   - 部分填写 → 汇报"上次做到第 X 步，从第 Y 步继续"
3. **把上下文读全**：
   - 问题报告全文 + `.codestable/attention.md`
   - 报告里提到的相关文件（用 Glob / Grep 找别只凭描述）
   - **扫 .codestable/ 全局**——Glob `.codestable/` 发现可用输入，按需取用：`architecture/`（涉及跨模块时读 ARCHITECTURE.md）、`compound/`（用 search-yaml.py 搜相关 trick / explore / learning，命中在分析开头标注引用）、`requirements/`（涉及能力边界时读）

---

## 分析的五步

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

### 步骤 1：定位问题代码

按报告"涉及模块 / 复现步骤"用 Grep / Glob 找：搜函数名 / 类名 / 文件名；沿调用链追溯（用户入口往下找）；重点看条件分支 / 边界值 / 状态更新 / 异步 / 数据流转。

记关键位置：`{文件}:{行号} — {这里干什么}`。

### 步骤 2：还原失败路径

对照复现步骤把代码执行路径走一遍：用户触发什么 → 调哪个函数 → 数据怎么流 → 哪里分叉走错。描述"正常路径"和"失败路径"的分叉点。**分叉点 = 根因候选**。

### 步骤 3：确认根因

单一 vs 多个根因；多个根因列出主次。

**根因分类**：
- 逻辑错误（条件判断 / 边界值缺失）
- 状态污染（副作用影响后续流程）
- 数据格式（输入 / 输出格式假设不符实际）
- 并发 / 竞态（异步顺序 / 共享状态）
- 配置 / 环境（依赖未稳定的配置）
- 缺少防御（没处理 null / undefined / 空列表等边界）

### 步骤 4：影响面评估

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

为什么复核：report 阶段给的是基于现象的判断，分析后看到了影响面——往往发现问题比看上去严重或没那么严重。

### 步骤 5：修复方案选项

列 2-3 种方向，每种说明：做什么（改哪里、怎么改）/ 优点 / 缺点和风险 / 影响面（会动哪些文件、影响其他功能吗）。

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

---

## 根因分析模板

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

# {问题简述} 根因分析

## 1. 问题定位

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

## 2. 失败路径还原

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

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

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

## 3. 根因

**根因类型**：{...}

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

**是否有多个根因**：{是 / 否。是的话列出主次}

## 4. 影响面

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

## 5. 修复方案

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

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

### 推荐方案

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

---

## checkpoint：和用户对齐

写完后**别直接开始修**：

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

---

## 退出条件

- [ ] frontmatter 存在（`doc_type=issue-analysis` / `issue` 一致）
- [ ] 5 节都填完
- [ ] 定位到具体代码位置（`{文件}:{行号}`）
- [ ] 失败路径还原清晰
- [ ] 影响面评估完成
- [ ] 至少 2 种修复方案 + 推荐
- [ ] 用户明确确认"分析准确，用方案 X 修"
- [ ] frontmatter `status: confirmed`

---

## 退出后

告诉用户："根因分析已就绪，方案已确认。下一步阶段 3 修复验证，触发 `cs-issue-fix`。"

别自己顺手改代码——跨阶段无停顿往下跑会让用户来不及把关。

---

## 容易踩的坑

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