cs-issue-analyze 用户已把问题描述清楚，你的活是 通过实际读代码找根因 ——不是脑子里推断、不是在报告基础上猜。读代码是核心动作，跳过它写出来的分析没价值。 分析完不直接动手——给用户看 2-3 种修复方案让 TA 选。原因：根因往往有多种修法，影响面 / 副作用 / 改动范围各不相同，这是用户该拍板的事。 共享路径与命名约定看 codestable/reference/shared-conventions.md 第 0 节和 cs-issue 的"文件放哪儿"。 启动检查 问题报告存在且已确认 ——读 {slug}-report.md ，确认 doc_type=issue-report 且 status=confirmed ，5 节都有内容。不完整 / 状态不对 → 回 cs-issue-report 。 cs-issue-report 已判走标准路径就按标准路径走，不二次改判 断点恢复 —— {slug}-analysis.md 已存在则检查 5 节哪些已填： 全部填满但 status=draft → 跳到 checkpoint 部分填写 → 汇报"上次做到第 X 步，从第 Y 步继续" 把上下文读全 ： 问题报告全文 + AGENTS.md 报告里提到的相关文件（用 Glob / Grep 找别只凭描述） codestable/architecture/ARCHITECTURE.md （涉及跨模块时） 归档检索（按需） ——只在问题涉及的模块曾有归档时搜： python codestable/tools/search-yaml.py --dir codestable/compound --query "{issue 关键词}" 按需追加 --filter doc_type=trick/explore/learning ，命中则在分析开头标注引用 分析的五步 每步都要 真正读代码 不要靠推测。 步骤 1：定位问题代码 按报告"涉及模块 / 复现步骤"用 Grep / Glob 找：搜函数名 / 类名 / 文件名；沿调用链追溯（用户入口往下找）；重点看条件分支 / 边界值 / 状态更新 / 异步 / 数据流转。 记关键位置： {文件}:{行号} — {这里干什么} 。 步骤 2：还原失败路径 对照复现步骤把代码执行路径走一遍：用户触发什么 → 调哪个函数 → 数据怎么流 → 哪里分叉走错。描述"正常路径"和"失败路径"的分叉点。 分叉点 = 根因候选 。 步骤 3：确认根因 单一 vs 多个根因；多个根因列出主次。 根因分类 ： 逻辑错误（条件判断 / 边界值缺失） 状态污染（副作用影响后续流程） 数据格式（输入 / 输出格式假设不符实际） 并发 / 竞态（异步顺序 / 共享状态） 配置 / 环境（依赖未稳定的配置） 缺少防御（没处理 null / undefined / 空列表等边界） 步骤 4：影响面评估 影响范围 ：只影响报告场景，还是更多场景？ 潜在受害者 ：哪些其他功能 / 模块可能被同一根因波及？ 数据完整性 ：会不会导致数据损坏或状态不一致？ 严重程度复核 ：和报告 P0/P1/P2/P3 对比是否需要调整？ 为什么复核：report 阶段给的是基于现象的判断，分析后看到了影响面——往往发现问题比看上去严重或没那么严重。 步骤 5：修复方案选项 列 2-3 种方向，每种说明：做什么（改哪里、怎么改）/ 优点 / 缺点和风险 / 影响面（会动哪些文件、影响其他功能吗）。 推荐方案 ：在 2-3 种里挑一种说明理由（通常：改动范围最小 + 根因最直接 + 副作用最少）。 根因分析模板
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 : [ ]
{问题简述} 根因分析
- 问题定位 | 关键位置 | 说明 | |
|
|
|
{文件}:{行号}
|
{干什么，为什么有问题}
|
- 失败路径还原
**
正常路径
**
：{用户做 A → 调用 B → 数据经过 C → 结果 D（符合期望）}
**
失败路径
**
：{用户做 A → 调用 B → 在 C 处因为 E 走了错误分支 → 结果 F（不符合期望）}
**
分叉点
**
：
{文件}:{行号}— {为什么这里走错}
- 根因 ** 根因类型 ** ：{...} ** 根因描述 ** ：{一段话说清为什么会发生，要能让没看过代码的人理解} ** 是否有多个根因 ** ：{是 / 否。是的话列出主次}
4. 影响面
** 影响范围 ** ：{只影响报告场景 / 还会影响 X、Y、Z} - ** 潜在受害模块 ** ：{列出可能被波及的} - ** 数据完整性风险 ** ：{有 / 无。有的话说明} - ** 严重程度复核 ** ：{维持 P? / 调整为 P?，理由}
- 修复方案
方案 A：{方案名}
** 做什么 ** ：{改哪里、怎么改} - ** 优点 ** ：{...} - ** 缺点 / 风险 ** ：{...} - ** 影响面 ** ：{会动哪些文件，会影响其他功能吗}
方案 B：{方案名}
...
推荐方案 ** 推荐方案 {A / B} ** ，理由：{改动范围最小 / 根因最直接 / 副作用最少 + 具体说明} checkpoint：和用户对齐 写完后 别直接开始修 ： 把"根因"和"推荐方案"口头总结给用户（不让用户读整份文件——TA 在等结论） 问"根因判断是否准确？推荐方案你认可，还是想选别的？" 用户明确确认方案后才触发阶段 3 退出条件 frontmatter 存在（ doc_type=issue-analysis / issue 一致） 5 节都填完 定位到具体代码位置（ {文件}:{行号} ） 失败路径还原清晰 影响面评估完成 至少 2 种修复方案 + 推荐 用户明确确认"分析准确，用方案 X 修" frontmatter status: confirmed 退出后 告诉用户："根因分析已就绪，方案已确认。下一步阶段 3 修复验证，触发 cs-issue-fix 。" 别自己顺手改代码——跨阶段无停顿往下跑会让用户来不及把关。 容易踩的坑 根因写"可能是某处的问题"——必须定位到 file:line 没读代码就靠问题描述推断——一定要实际 Grep / Read 只列一种修复方案——至少两种 分析完直接开始改代码——必须等用户确认 影响面写"可能影响其他功能"——要具体说哪些 严重程度复核总是"维持"——认真看影响面，升级的要改