📄 本页由源文件 skills/issue-trace/SKILL.md 自动投影生成（单一权威源）。请勿直接编辑本页。

issue-trace

定位：纯分析阶段的根因诊断中枢。用户描述了一个问题现象，想搞清楚"为什么会这样"，但还没决定要不要修。 核心动作：表象 → 嫌疑点 → 反向追溯 → 根因定论 + 证据链 + 修复建议（不自动进入修复）。 核心原则：证据驱动结论 + 不自动升级 dev-flow + 调用链辅助呈现而非主体。

设计理念

用户描述现象（表象）
   ↓
列出嫌疑点（≥2 条，避免单点假设）
   ↓
反向追溯（沿调用栈/数据流/依赖链）→ 跨项目时强制走 reflex 三步法
   ↓
根因定论（已定 / 未定+待验证假设）+ 证据链
   ↓
修复建议（治本 + 治标 双方案，仅建议不动手）
   ↓
由用户决定下一步（修 → 走 dev-flow / 不修 → 结束）

与其他 skill 的边界：

场景	入口	走哪
任务平台 bug 链接 + 明确要修	任务平台 URL + 修复动词	`bugfix-skill`
已决定要修复（"帮我修这个"）	修复动词	`dev-flow` / `bugfix-skill`
描述现象想搞清楚为什么 / 想追溯调用链	现象描述 / 追溯动词	issue-trace（本 skill）

全局输出规范（最高优先级）

本 Skill 生成的所有根因报告、调用链、证据引用，文件路径、代码位置引用必须遵循 ~/.codebuddy/rules/AI行为规范.mdc 的「文件/代码位置引用」规范（反引号包裹相对路径 `相对路径` + 空格后缀行号 L行号）。跨项目分析时必须叠加来源标注（见下文 §「调用链与证据链输出格式」）。

触发规则

🏛️ 单一权威源：本章节是 issue-trace 触发规则的唯一权威源。~/.codebuddy/rules/AI行为规范.mdc 仅保留决策指令与优先级，具体动词/场景一律在此维护。

⚡ 显式命令（最高优先级，无歧义）

命令	快捷	说明
`trace`	`t`	进入 issue-trace 完整 5 步分析流程
`trace --quick`	`t -q`	轻量模式：直接给结论，跳过物理门控
`trace --chain`	`t -c`	链路模式：侧重跨项目调用链追溯
`trace --suspects`	`t -s`	只输出嫌疑点列表（Step 1-2），暂不追溯
`trace --resume`	`t -r`	恢复模式：加载最近未闭环的 trace 快照，继续分析
`trace --list`	`t -l`	列出所有未闭环（open/handed-off）的 trace 记录
`trace --close <id>`	`t --close <id>`	手动关闭某次分析（已解决/放弃）

用法：在 CodeBuddy 对话中输入命令 + 问题描述即可，例如：

trace 为什么 Avatar 组件在中文环境下显示英文
t -c list-component 的 ShareModal 调用链怎么走的
t -s 详情页偶现白屏
t -r                              ← 在新项目中恢复上次分析
t -l                              ← 查看所有未闭环的分析
t --close trace-20260526-173000   ← 关闭已解决的分析

命令解析规则：

命令后跟的文本作为「现象描述」输入 Step 1
-q / --quick 跳过物理门控，输出末尾附加置信度警告
-c / --chain 自动进入 Step 3 跨项目追溯路径（reflex 三步法）
-s / --suspects 完成 Step 2 后暂停，等用户选择是否继续深入
-r / --resume 读取 traces/ 目录下最近一条 status: open 或 status: handed-off 的快照，自动加载上下文后从中断点继续分析
-l / --list 扫描 traces/ 目录，列出所有非 closed 状态的 trace 摘要（id + 标题 + 状态 + 创建时间）
--close <id> 将指定 trace 文件的 status 改为 closed，追加关闭时间

💡 与 dev-flow 的关系：trace 是 issue-trace skill 的独立命令。如果分析完用户选择修复，会自然衔接到 dev-flow。

🔴 不触发场景（前置排除，避免误抢入口）

#	条件	该走哪
N1	消息含任务平台链接 + 明确修复动词（"帮我修"、"fix 这个"）	`bugfix-skill`
N2	用户明确说"帮我修复 XX" / "改一下 XX" / "把 XX 改成 YY"（无追溯诉求）	`dev-flow` / `bugfix-skill`
N3	元讨论：修改/讨论 issue-trace skill 自身的规则/流程	普通对话

🟡 显式触发（用户直说"分析根因/追溯"或使用命令）

用户说的话	行为
`trace` / `t` / `trace --quick` / `trace --chain` / `trace --suspects` / `trace --resume` / `trace --list` / `trace --close`	命令触发（最高优先级，无歧义）
"排查根因" / "定位根因" / "分析根因" / "找根因" / "根因定位" / "根因分析"	完整流程
"深度分析" / "深入分析" / "深挖" / "深究" / "彻查"	完整流程
"trace 一下" / "追踪一下" / "追溯一下" / "查清楚" / "搞清楚为什么"	完整流程

🟢 现象描述型触发（最高频，用户描述问题但没说要修）

用户说的话（典型句式）	触发判定
"为什么会这样" / "为啥会这样" / "为什么会出现 XX" / "为啥出现 XX"	✅ 触发
"这个值从哪来" / "这个参数为什么是 XX" / "这个数据怎么来的"	✅ 触发
"这段逻辑是怎么走的" / "这里怎么会走到这" / "整个流程是什么" / "什么情况下会触发"	✅ 触发

🔵 困惑/不确定型触发（用户在分析阶段）

用户说的话	触发判定
"我不确定哪里有问题" / "可能是哪里的问题" / "嫌疑点有哪些"	✅ 触发
"帮我看下问题在哪" / "帮我分析下问题" / "帮我看看这段代码"	✅ 触发
"问题表象是 XX" / "表面看是 XX 但" / "看起来像 XX 的问题" / "疑似是 XX 的原因"	✅ 触发

🟣 跨项目链路型触发（用户已意识到涉及多项目）

用户说的话	触发判定
"完整调用链" / "调用链路" / "调用链" / "链路追踪" / "链路分析"	✅ 触发
"跨项目分析" / "跨包追溯" / "依赖链" / "依赖追溯"	✅ 触发
"从 A 到 B 到 C 是怎么走的" / "哪个项目出的问题"	✅ 触发

⚠️ 触发判断可观测性：判定为 issue-trace 触发时，必须在回复开头用一行说明（如"本次走 issue-trace 根因诊断流程，不进入 dev-flow"），让用户可监督判断是否正确（与 AI 行为规范 §「触发判断可观测性」对齐）。

命令参数与工作流映射

命令/参数	执行步骤	物理门控	输出
`trace`（默认，无参数）	Step 1→2→3→4→5 完整流程	✅ 必须执行	完整根因报告
`--quick` / `-q`	Step 1→2→3→4→5（简化）	⚠️ 跳过，附加置信度警告	极简结论 + 嫌疑点 + 建议
`--chain` / `-c`	Step 1→2→3（加强跨项目）→4→5	✅ 必须执行	重点展示 ASCII 调用链树
`--suspects` / `-s`	Step 1→2（暂停）	❌ 不触发（未到输出阶段）	嫌疑点列表 + "是否继续深入？"
`--resume` / `-r`	加载 trace 快照 → 从中断的 Step 继续	✅ 必须执行	接续之前的分析流程
`--list` / `-l`	扫描 traces/ 目录	❌ 无需	未闭环 trace 摘要列表
`--close <id>`	更新 trace 文件状态	❌ 无需	确认关闭消息

💡 参数可组合：t -q -c = 快速给出跨项目调用链结论（跳过门控）

工作流程（5 步法，强制顺序）

Step 1：现象输入解析

收集 4 类信息（用户没主动给的要主动追问，但每轮最多问 2 项，避免审讯感）：

信息项	必填	用途
现象描述（看到什么/不期望什么）	✅	反向追溯起点
触发条件（什么操作/什么环境复现）	✅	缩小排查范围
涉及模块/文件/接口（用户已知部分）	⭕	加速嫌疑点拆解
期望行为 vs 实际行为	⭕	明确"问题"边界

Step 2：嫌疑点拆解（≥2 条，强制）

反单点假设：任何根因分析必须先列出 ≥2 条嫌疑点，禁止上来就锁定单一原因。

输出格式：

markdown

## 嫌疑点列表
1. **[嫌疑 A]** {1 句话假设} — 验证方式：{读哪个文件/查哪个数据}
2. **[嫌疑 B]** {1 句话假设} — 验证方式：{读哪个文件/查哪个数据}
3. **[嫌疑 C]**（可选）...

Step 3：反向追溯（核心）

按 4 类追溯路径并行展开：

追溯类型	起点	工具
代码逻辑追溯	现象代码位置 → 调用方/被调用方	`grep_search` / `view_code_item` / `read_file`
数据流追溯	异常值出现位置 → 该值来源	grep + 反向沿 props/参数/state 找源头
依赖链追溯	当前 workspace → `node_modules/@your-org/*` → 上游包源码	强制走『跨项目分析 reflex 三步法』
日志追溯（线上现象时）	用户描述线上错误/异常 → 查日志确认模式	`SearchLog` / `LogClassify`（需配置日志 MCP 工具）
历史追溯（按需）	文件变更历史	`get_file_blame` / `get_commits_list`（可选）

🚨 跨项目追溯硬约束（与 ~/.codebuddy/rules/AI行为规范.mdc §「跨项目分析 reflex 原则」对齐）：
检测到非当前 workspace 的依赖包/上游组件库时，禁止凭推测、禁止仅依赖远端知识库平台 MCP
必须执行 reflex 三步法：① 本地优先探测项目路径 ② 命中本地先做分支感知 ③ 未命中主动提醒用户 4 选项（clone / 知识库 MCP / API 获取代码 / 跳过）
引用本地仓库源码时必须标注 [local-repo] 或 [local-repo@{branch}] 来源
完整流程见 skills/dev-flow/references/cross-project-flow.md §「分析型跨项目流程」

Step 4：根因定论

输出三选一（禁止含糊其辞）：

状态	何时使用	输出要求
✅ 已定根因	证据充分（≥2 条独立证据指向同一原因）	给出根因 + 证据链 + 调用链 + 修复建议
🟡 高度疑似根因	证据指向但缺一环验证（如需运行时数据）	给出最可能根因 + 待验证项清单 + 用户验证指引
🔴 未定根因	嫌疑点均未排除/缺关键信息	列出剩余嫌疑点 + 每条的下一步排查动作 + 向用户索要哪些信息

Step 5：输出格式（统一模板）

🚨 输出顺序强约束（必须按以下顺序，禁止打乱）：根因定论 → ASCII 调用链树（主体）→ 关键代码位置 → 证据链 → 修复建议 → 下一步
🚨 调用链格式硬约束：
主体必须用 ASCII 树（如下模板），便于终端复制 + IDE 内联展示 + 跨平台稳定渲染
禁止用 mermaid 图片作为调用链主体（用户已明确反馈不要图片）
仅当链路 ≥ 5 节点且分支 ≥ 2 条时，可在 ASCII 树之后附加 mermaid 作为辅助视图（非替代）
🚨 代码块原文 100% 一致约束（违反即拒收）：
所有 ```ts/tsx/js ``` 代码块内容必须等于磁盘原文
禁止在代码块内添加 // ❌ // ⚠️ // 🚨 // root cause 等原文不存在的评价性注释
需要标注时，把评价写在代码块外（如「⭐ 关键证据 N：xxx」）

markdown

## 🎯 根因定论
{已定 / 高度疑似 / 未定}：{1 句话结论}

## 🔗 完整调用链（ASCII 树）
\```
funcA(args)                                  ← `my-project/src/x.tsx` L42
  └─ funcB(options)                          ← `component-lib/src/y.tsx` L120 [local-repo]
        └─ funcC(params)                     ← `base-project/src/z.ts` L88 [local-repo@feature/xxx]
              └─ rootCauseField              ← `base-project/src/z.ts` L95 [local-repo@feature/xxx] 🚨 root cause
\```

## 📍 关键代码位置（按调用顺序）
1. `my-project/src/x.tsx` L42-L58 `[当前 workspace]` — {1 句话说明此处的角色}
   ```tsx
   // 关键 3-5 行代码

component-lib/src/y.tsx L120 [local-repo] —
tsx
```
// 关键 3-5 行代码
```
base-project/src/z.ts L88 [local-repo@feature/xxx] —
ts
```
// 关键 3-5 行代码（root cause）
```

🧪 证据链

证据 1：{是什么 + 在哪} → 支撑/排除哪条嫌疑
证据 2：...

💡 修复建议（仅建议，不自动执行）

治本方案：{改 X 项目的 Y 处，影响范围 Z} — 推荐
治标方案：{在当前项目 W 处加防御} — 风险/副作用：...

🚦 下一步

选 1：进入 dev-flow 修复 → 我会 use_skill('dev-flow')
选 2：先用治标方案应急 → 告诉我我帮你写补丁（仍走 dev-flow）
选 3：信息不足，先补充 {具体信息} 再分析 → 普通对话继续
选 4：暂不修复 → 本次分析结束
选 5：需跨项目继续 → 生成 trace 快照，去目标项目新开对话用 t -r 衔接


---

## 调用链与证据链输出格式（强制）

| 引用对象 | 格式 |
|---------|------|
| 当前 workspace 文件 | `` `相对路径` `` L行号（默认，可省略来源标签） |
| 跨项目本地仓库（默认分支） | `` `仓库名/相对路径` `` L行号 `[local-repo]` |
| 跨项目本地仓库（非默认分支） | `` `仓库名/相对路径` `` L行号 `[local-repo@{branch}]` |
| 远端 知识库平台 MCP 拉取 | `` `仓库名/相对路径` `` L行号 `[知识库平台@{commit-sha7}]` |
| Git 平台 get_blob_content 拉取 | `` `仓库名/相对路径` `` L行号 `[代码平台@{ref}]` |

> 与 AI 行为规范 §「输出格式规范」+「跨项目分析 reflex 原则 §来源标注」双向闭环。

---

## 外部参考

> 日志追溯：当问题涉及线上现象，可结合日志查询 MCP 工具（如 `SearchLog`、`LogClassify`）确认错误模式后，切回 Step 3 代码逻辑追溯继续深入分析。日志查询仅用于确认线上现象，不作为根因定论的主要证据。

---

## 输出前物理事实门控（强制，与 dev-flow `.validated` 哲学对齐）

> 🏛️ **设计哲学**：`~/.codebuddy/rules/AI行为规范.mdc` §「Skill 设计哲学」明确——**确定性用代码，模糊性用 LLM**。
> 本章节是 issue-trace 的**物理事实兜底**：把"调用方追溯到位""代码块原文一致"这两条**确定性可程序化**的检查从提示词层下沉到脚本层，AI 不可绕过。

### 触发条件

完成 Step 5 输出**之前**（即生成根因报告 markdown 之前），**必须**对自己即将输出的报告内容做以下两项物理校验：

| 检查项 | 脚本 | 退出码 0 才算通过 |
|--------|------|------------------|
| 调用方追溯深度 | `scripts/trace-depth-check.sh <报告.md>`（v2 纯报告自检）| 报告内 wrapper import 同时必须有实现位置（包名/路径 + L行号）|
| 代码块原文一致性 | `scripts/code-block-purity-check.sh <报告.md>` | 代码块内无自创评价性注释 |

### 执行范式（不可绕过）

```bash
# Step A: 把即将输出的报告先写到临时文件（编辑工具自带 success 不算落盘）
REPORT_TMP=$(mktemp -t issue-trace-report-XXXXXX.md)
cat > "$REPORT_TMP" <<'EOF'
{即将输出给用户的根因报告 markdown 全文}
EOF

# Step B: 运行两个门控脚本（顺序无关，可并行）
bash ~/.codebuddy/skills/issue-trace/scripts/trace-depth-check.sh "$REPORT_TMP"
TRACE_RC=$?
bash ~/.codebuddy/skills/issue-trace/scripts/code-block-purity-check.sh "$REPORT_TMP"
PURITY_RC=$?

# Step C: 任一非 0 → 必须先修报告再重跑，禁止把不合格内容输出给用户
if [[ $TRACE_RC -ne 0 || $PURITY_RC -ne 0 ]]; then
  echo "❌ 物理门控未通过，需修订报告后重跑"
  # 此时回到 Step 3-4 补全追溯链路 / 清理代码块自创注释
fi

例外条款（务实主义）

快速咨询模式：报告中没有代码块且未引用任何源文件路径 → 跳过两项门控（无可校验对象）
轻量分析模式：用户明确说"先给个结论就行" → 输出极简结论 + 在末尾追加 ⚠️ 已跳过物理门控（轻量模式），结论可信度需用户自行判断
门控误报：如果脚本误报（如 wrapper 函数实际无追溯必要），必须在报告末尾显式说明误报理由，而不是静默跳过

反模式（违反即拒收）

❌ 编辑工具回报 success 就直接发输出，不走两个门控脚本
❌ grep_search/codebase_search 显示通过就当作物理门控通过（与 AI 行为规范 §「编辑工具假性成功兜底」对齐）
❌ 门控脚本退出非 0 时强行输出，不修报告
❌ 把跳过门控当作"用户没要求"的默认行为（默认必须执行，例外条款必须显式声明）

反模式（违反即拒收）

❌ 单点假设：上来就锁定单一原因，不列嫌疑点 → 必出错判
❌ 凭推测跨项目：检测到外部依赖包不去本地查实际代码 → 违反 reflex 三步法
❌ 未做分支感知：本地仓库分支与期望不一致仍直接读源码 → 可能拿到 feature 分支的中间状态代码
❌ 自动升级 dev-flow：用户没说要修就替用户决定进入修复流程 → 违反"不自动升级"承诺
❌ 结论模糊：输出"可能是 X 也可能是 Y"但不给定论状态/不给下一步 → 用户无法行动
❌ 无证据链：只给结论不给"哪个文件哪一行支撑了这个结论" → 无法被用户验证
❌ 遗漏来源标注：跨项目引用没标 [local-repo] / [local-repo@branch] / [知识库平台@sha] → 用户无法判断证据时效性
❌ 不限定修复建议范围：在分析阶段直接动手改代码 → 越权（本 skill 只建议不动手，要改必须经 dev-flow）
❌ 调用方追溯偷懒（2026-05-20 新增）：业务函数调用了 get/post/request/fetch/http 等通用名时，必须追到该函数内部至少一层（看是不是 wrapper），禁止凭「看起来很简单」就停在第一层。判定标准：报告引用了 A 文件的 xxx() 调用，但 A 文件中 xxx 是从 B 文件 import 的本地函数 → 报告必须同时引用 B 文件 xxx 的实现行号。与「§祖父原则 §B 调用方追溯」对齐
❌ 代码块自创注释污染（2026-05-20 新增）：在引用源码时，代码块内严禁出现 // ❌ / // ⚠️ / // 🚨 / // root cause / // 这里是问题 等原文不存在的评价性注释。需要标注关键点时，必须把评价写在代码块外（如「⭐ 关键证据 N：xxx」），代码块内必须 100% 等于磁盘原文。判定方法：用 sed -n '起,止p' 文件 提取真实内容，与报告代码块字符级比对，任意自创注释 → 拒收

跨对话衔接（Trace Handoff）

设计理念：把 AI 脑中的分析中间态「物化」到文件，使跨对话、跨项目的分析流程不再断裂。

目录结构

~/.codebuddy/skills/issue-trace/traces/
├── .gitkeep
├── TEMPLATE.md                          ← 快照模板（不可删除）
├── 2026-05-26_avatar-i18n.md            ← 具体分析快照
├── 2026-05-24_share-modal-crash.md
└── ...

文件命名规范

{YYYY-MM-DD}_{问题关键词-kebab-case}.md

日期取创建时间
关键词 2-4 个单词，用连字符连接，全小写
例：2026-05-26_avatar-i18n-fallback.md

状态流转

open → handed-off → closed
  │         │
  └────→ closed（直接在当前项目解决）

状态	含义
`open`	分析进行中，尚未确认需跨项目
`handed-off`	已确认需跨项目继续，快照已生成，等待在目标项目恢复
`closed`	分析已完成（根因已定 / 已修复 / 用户放弃）

快照生成时机

以下任一条件满足时，必须提议生成 trace 快照（用户确认后才写入）：

用户选择下一步选项 5（需跨项目继续）
Step 3 追溯自然中断：追到非当前 workspace 的代码且本地无该仓库
Step 4 结论为 🟡 高度疑似且根因指向外部项目
用户主动说"先到这"/"我去另一个项目看看"

`trace --resume` 执行流程

用户在目标项目输入 t -r
  ↓
① 扫描 ~/.codebuddy/skills/issue-trace/traces/ 下所有 .md 文件
  ↓
② 找到 status: open 或 status: handed-off 的文件
  ↓
③ 如果有多条，按 created 倒序列出，让用户选择；仅一条则自动加载
  ↓
④ 读取快照内容，解析 frontmatter
  ↓
⑤ 将「现象摘要」作为 Step 1 输入、「剩余嫌疑点」作为 Step 2 起点、
   「下一步排查指引」作为 Step 3 的追溯方向
  ↓
⑥ 从中断点继续分析流程（通常从 Step 3 开始）
  ↓
⑦ 分析完成后，更新原快照的 status → closed，追加闭环信息

`trace --list` 执行流程

bash

# 扫描 traces/ 目录，过滤非 closed 的文件，输出摘要表格

输出格式：

| # | ID | 标题 | 状态 | 创建时间 | 来源项目 → 目标项目 |
|---|-------|------|------|---------|-------------------|
| 1 | trace-20260526-173000 | 用户头像组件显示异常 | handed-off | 2026-05-26 | my-app → component-lib |
| 2 | trace-20260524-091500 | 弹窗组件渲染错误 | open | 2026-05-24 | my-app → — |

`trace --close <id>` 执行流程

在 traces/ 目录中找到匹配 id 的文件
将 frontmatter 中 status 改为 closed
追加 closed_at: {ISO8601} 和 close_reason: {用户提供或默认"手动关闭"}

快照自动过期清理

closed 状态超过 30 天的文件 → 移入 traces/archive/（不删除）
open 状态超过 7 天未有任何更新 → 下次 t -l 时标注 ⚠️ 超期，提醒用户决定是否关闭
清理动作仅在用户执行 t -l 时触发，不后台自动运行

快照与 dev-flow working-context 的关系

trace 快照不等于 working-context flow 文件
trace 快照是「分析中间态」，working-context 是「修复执行态」
用户选择"修"后，dev-flow 会从 trace 快照中提取关键信息初始化 flow 文件，但两者独立管理
trace 快照在 ~/.codebuddy/skills/issue-trace/traces/，跨项目共享
working-context 在 ~/.codebuddy/working-context/，与当前对话绑定

反模式

❌ 未经用户确认就生成快照：必须先提议，用户确认后才写文件
❌ 在快照中复制完整源码：只记关键 3-5 行 + 文件位置，不做大段 copy
❌ t -r 时不验证当前 workspace 与 handoff_target 的匹配：恢复时应提醒用户确认
❌ closed 的 trace 被 t -r 恢复：只恢复 open/handed-off 状态

不会自动触发 dev-flow 的承诺

本 Skill 完成 5 步流程后，输出截止于「修复建议 + 下一步选项」
是否进入 dev-flow 由用户在 §「下一步」中显式选择
用户选择"修"后，AI 才能 use_skill('dev-flow') 进入修复流程
此承诺与 AI 行为规范 §「工作上下文文件保护」对齐：未触发 dev-flow 期间禁止操作 working-context/

与现有规则的引用闭环

引用方向	来源	落点
issue-trace → AI 行为规范	`~/.codebuddy/rules/AI行为规范.mdc` §「跨项目分析 reflex 原则」	本文件 §「Step 3 跨项目追溯硬约束」
issue-trace → cross-project-flow	`skills/dev-flow/references/cross-project-flow.md` §「分析型跨项目流程」	本文件 §「Step 3」
AI 行为规范 → issue-trace	本文件 §「触发规则」	`rules/AI行为规范.mdc` §「Skill 触发优先级」
cross-project-flow → issue-trace	本文件 §「Step 3 跨项目追溯」	`cross-project-flow.md` §「分析型跨项目流程 / 全量场景适用」

双向闭环验证命令：

bash

grep -n "issue-trace" ~/.codebuddy/rules/AI行为规范.mdc
grep -n "issue-trace" ~/.codebuddy/skills/dev-flow/references/cross-project-flow.md

issue-trace ​

设计理念 ​

全局输出规范（最高优先级） ​

触发规则 ​

⚡ 显式命令（最高优先级，无歧义） ​

🔴 不触发场景（前置排除，避免误抢入口） ​

🟡 显式触发（用户直说"分析根因/追溯"或使用命令） ​

🟢 现象描述型触发（最高频，用户描述问题但没说要修） ​

🔵 困惑/不确定型触发（用户在分析阶段） ​

🟣 跨项目链路型触发（用户已意识到涉及多项目） ​

命令参数与工作流映射 ​

工作流程（5 步法，强制顺序） ​

Step 1：现象输入解析 ​

Step 2：嫌疑点拆解（≥2 条，强制） ​

Step 3：反向追溯（核心） ​

Step 4：根因定论 ​

Step 5：输出格式（统一模板） ​

🧪 证据链 ​

💡 修复建议（仅建议，不自动执行） ​

🚦 下一步 ​

例外条款（务实主义） ​

反模式（违反即拒收） ​

反模式（违反即拒收） ​

跨对话衔接（Trace Handoff） ​

目录结构 ​

文件命名规范 ​

状态流转 ​

快照生成时机 ​

trace --resume 执行流程 ​

trace --list 执行流程 ​

trace --close <id> 执行流程 ​

快照自动过期清理 ​

快照与 dev-flow working-context 的关系 ​

反模式 ​

不会自动触发 dev-flow 的承诺 ​

与现有规则的引用闭环 ​

issue-trace

设计理念

全局输出规范（最高优先级）

触发规则

⚡ 显式命令（最高优先级，无歧义）

🔴 不触发场景（前置排除，避免误抢入口）

🟡 显式触发（用户直说"分析根因/追溯"或使用命令）

🟢 现象描述型触发（最高频，用户描述问题但没说要修）

🔵 困惑/不确定型触发（用户在分析阶段）

🟣 跨项目链路型触发（用户已意识到涉及多项目）

命令参数与工作流映射

工作流程（5 步法，强制顺序）

Step 1：现象输入解析

Step 2：嫌疑点拆解（≥2 条，强制）

Step 3：反向追溯（核心）

Step 4：根因定论

Step 5：输出格式（统一模板）

🧪 证据链

💡 修复建议（仅建议，不自动执行）

🚦 下一步

例外条款（务实主义）

反模式（违反即拒收）

反模式（违反即拒收）

跨对话衔接（Trace Handoff）

目录结构

文件命名规范

状态流转

快照生成时机

`trace --resume` 执行流程

`trace --list` 执行流程

`trace --close <id>` 执行流程

快照自动过期清理

快照与 dev-flow working-context 的关系

反模式

不会自动触发 dev-flow 的承诺

与现有规则的引用闭环