菜单
issue 流程阶段 2——读 report + 读代码定位根因、评估风险，给用户 2-3 个修复方案让 TA 拍板。这一步不改代码。触发：用户说"分析这个 bug"、"找根因"、"定位问题"，且已有 {slug}-report.md。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
维护 `.kflow/architecture/` 这份只记现状的系统地图，三种模式 update / check / backfill。触发：用户说"刷新 architecture"、"做架构检查"、"补这个模块的架构文档"、"方案和代码对得上吗"，或 feature 阶段需要先做架构动作。不写未来规划（走 k-roadmap）。
feature 流程阶段 3——验收闭环：对照 design 核实现 + 回写 architecture / requirement / roadmap，最后产出 {slug}-acceptance.md。触发：用户说"功能写完了验收一下"、"做最后检查"、"准备 merge"、"出验收报告"。前置依赖 k-feat-impl 完成。
feature 流程阶段 1——为新功能起草 {slug}-design.md 作为后续实现和验收的唯一输入，拍板后抽出 checklist。触发：用户说"开始设计方案"、"写 design doc"、"准备实现 XX"，前提是已知道做什么、为谁、怎么算成功。
feature 流程阶段 2——按 {slug}-checklist.yaml 里 design 切好的 paradigm 维度 steps 推进，每步具体改哪个文件由 implement 自决，写完用统一格式汇报。触发：用户说"方案确认了开始实现"、"按方案写代码"、"开工"。前提是 design 已 approved 且有 checklist。遇到方案外情况要回方案谈不要硬冲。
issue 流程阶段 3——按已确认根因和方案定点修复、验证、写 {slug}-fix-note.md 落档。两个入口：标准路径从 analyze 来，快速通道从 report 直接来。触发：用户说"开始修 bug"、"按分析修"、"动手改代码"。只动方案声明的文件，不顺手优化。
把新仓库或有零散文档的仓库接入 kflow 体系——两条路径自动判断：空仓库从零搭骨架，已有文档走审计 + 迁移映射——然后释放技能文件和跨平台入口（AGENTS.md，可选 CLAUDE.md）。触发：用户说"在这个项目里用 kflow"、"搭 kflow 结构"、"初始化 kflow"、"迁移到 kflow"。
| name | k-issue-analyze |
| description | issue 流程阶段 2——读 report + 读代码定位根因、评估风险，给用户 2-3 个修复方案让 TA 拍板。这一步不改代码。触发：用户说"分析这个 bug"、"找根因"、"定位问题"，且已有 {slug}-report.md。 |
开始任何判断或动作前，先读取 .kflow/attention.md；缺失则视为骨架不完整，提示先补齐或运行 k-onboard。
用户已把问题描述清楚，你的活是通过实际读代码找根因——不是脑子里推断、不是在报告基础上猜。读代码是核心动作，跳过它写出来的分析没价值。
分析完不直接动手——给用户看 2-3 种修复方案让 TA 选。原因：根因往往有多种修法，影响面 / 副作用 / 改动范围各不相同，这是用户该拍板的事。
共享路径与命名约定看
.kflow/reference/shared-paths.md和k-issue的"文件放哪儿"。读取材料遵守.kflow/reference/shared-token-budget.md，先按报告字段和复现线索定位代码，不批量读无关历史文档。
{slug}-report.md，确认 doc_type=issue-report 且 status=confirmed，5 节都有内容。不完整 / 状态不对 → 回 k-issue-report。k-issue-report 已判走标准路径就按标准路径走，不二次改判{slug}-analysis.md 已存在则检查 5 节哪些已填：
status=draft → 跳到 checkpoint.kflow/attention.md.kflow/ 发现可用输入，按需取用：architecture/（涉及跨模块时先读 ARCHITECTURE.md 索引，再读相关 doc 小节）、compound/（用 search-yaml.py 搜相关 trick / explore / learning，默认只读最高相关 1-3 个命中）、requirements/（涉及能力边界时读相关故事 / 边界节）每步都要真正读代码不要靠推测。
按报告"涉及模块 / 复现步骤"用 Grep / Glob 找：搜函数名 / 类名 / 文件名；沿调用链追溯（用户入口往下找）；重点看条件分支 / 边界值 / 状态更新 / 异步 / 数据流转。
记关键位置：{文件}:{行号} — {这里干什么}。
对照复现步骤把代码执行路径走一遍：用户触发什么 → 调哪个函数 → 数据怎么流 → 哪里分叉走错。描述"正常路径"和"失败路径"的分叉点。分叉点 = 根因候选。
单一 vs 多个根因；多个根因列出主次。
根因分类：
为什么复核：report 阶段给的是基于现象的判断，分析后看到了影响面——往往发现问题比看上去严重或没那么严重。
列 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: []
---
# {问题简述} 根因分析
## 1. 问题定位
| 关键位置 | 说明 |
|---|---|
| `{文件}:{行号}` | {干什么，为什么有问题} |
## 2. 失败路径还原
**正常路径**：{用户做 A → 调用 B → 数据经过 C → 结果 D（符合期望）}
**失败路径**：{用户做 A → 调用 B → 在 C 处因为 E 走了错误分支 → 结果 F（不符合期望）}
**分叉点**：`{文件}:{行号}` — {为什么这里走错}
## 3. 根因
**根因类型**：{...}
**根因描述**：{一段话说清为什么会发生，要能让没看过代码的人理解}
**核心证据代码**：`{文件}:{起始行}-{结束行}`（贴 3-10 行最关键原始代码，直接支撑上面的根因判断）
**是否有多个根因**：{是 / 否。是的话列出主次}
## 4. 影响面
- **影响范围**：{只影响报告场景 / 还会影响 X、Y、Z}
- **潜在受害模块**：{列出可能被波及的}
- **数据完整性风险**：{有 / 无。有的话说明}
- **严重程度复核**：{维持 P? / 调整为 P?，理由}
## 5. 修复方案
### 方案 A：{方案名}
- **做什么**：{改哪里、怎么改}
- **优点**：{...}
- **缺点 / 风险**：{...}
- **影响面**：{会动哪些文件，会影响其他功能吗}
### 方案 B：{方案名}
- ...
### 推荐方案
**推荐方案 {A / B}**，理由：{改动范围最小 / 根因最直接 / 副作用最少 + 具体说明}
写完后别直接开始修：
doc_type=issue-analysis / issue 一致）{文件}:{行号}）file:line）status: confirmed告诉用户："根因分析已就绪，方案已确认。下一步阶段 3 修复验证，触发 k-issue-fix。"
别自己顺手改代码——跨阶段无停顿往下跑会让用户来不及把关。