cc-devflow 4.5.11 → 4.5.12

package/.claude/skills/cc-investigate/PLAYBOOK.md

@@ -1,192 +1,32 @@
 # CC-Investigate Playbook
 
-## Visible State Machine
+## State Machine
 
 `cc-investigate -> cc-do -> cc-check`
 
-- Enter from: a bug, regression, or broken requirement whose root cause is still unclear.
-- Stay in: `cc-investigate` until `planning/tasks.md#Root Cause Contract` and the repair handoff are both frozen.
-- Exit to: `cc-do` only after root cause, repair boundary, and source roadmap progress are explicit in canonical artifacts.
-- Reroute to: `cc-plan` for scope/design truth changes, or `roadmap` for project-level priority decisions.
+- Enter when root cause is unknown.
+- Stay until `task.md#Root Cause Contract` is evidence-backed.
+- Exit after the Investigate commit exists.
 
-## Core Rules
+## Rules
 
-1. 先复现，再猜原因。
-2. 先把复现做成快、准、可复跑的 feedback loop。
-3. 先确认 loop 复现的是用户报告的同一个失败。
-4. 先看最近变化，再决定是不是 regression。
-5. 先证伪假设，再冻结根因。
-6. `planning/tasks.md` 必须足够让 `cc-do` 脱离当前会话继续工作。
-7. 调查失败三次后先重建入口，不准继续乱补。
-8. 没有 frozen root-cause contract，不准进入 repair task。
-9. 多组件、深层调用、flaky 问题必须先补边界探针、反向追踪或条件等待证据。
-10. diagnose-only 只能输出根因、owner、风险和 next action，不能把未修复状态标成完成。
-11. workflow forensics 先分类 artifact / git / state / tool / permission / process failure，再决定是否进入修复。
-12. 退出前必须跑 Roadmap Sync Gate：`implementation drift`、`missing spec truth`、`roadmap mismatch` 三种结论都要让 source RM 的状态和 next action 跟上。
-13. Root Cause Proof Ladder 必须证明 symptom site、first bad state、violated contract、original trigger、counterfactual proof 和 escape reason。
-14. 分配 `FIX-*` change key 后立刻执行 Worktree Branch Contract：detached worktree 先挂到 `FIX/<task>`；当前在 `main` / default branch 时停止，不写 investigation artifacts。
-
-## Iron Law
-
-```text
-NO REPAIR WITHOUT A FROZEN ROOT-CAUSE CONTRACT
-```
-
-root-cause contract 至少包含：稳定复现或缩小后的可验证症状、被破坏的代码 / 配置 / 数据 / 依赖契约、已证伪假设、最小修复边界。
-
-## Root Cause Proof Ladder
-
-根因要从“看到错误的地方”追到“错误第一次被制造的地方”：
-
-1. `L1 Symptom Site`：用户看到的失败。
-2. `L2 First Bad State`：第一个坏字段、坏 artifact、坏队列消息、坏配置或坏状态。
-3. `L3 Violated Contract`：被破坏的 schema、invariant、state transition、权限边界或协议。
-4. `L4 Original Trigger`：制造坏状态的用户动作、命令、事件、recent diff、配置或外部响应。
-5. `L5 Counterfactual Proof`：恢复 contract 或替换输入后，症状变化的实际观察。
-6. `L6 Escape Reason`：为什么测试、类型、review、监控或 artifact gate 没挡住。
-
-缺 `L2`、`L4` 或 `L5` 时，`planning/tasks.md#Root Cause Contract` 只能写 `needs-more-evidence`、`Evidence Request` 或 reroute，不能生成 `cc-do` repair task。
-
-## Required Outputs
-
-- `planning/tasks.md`
-- `planning/task-manifest.json`
-- `change-meta.json`
-
-## Investigation Standard
-
-1. 先收集 symptom、expected、actual、repro。
-2. 先构造 feedback loop：失败测试、HTTP 脚本、CLI fixture、浏览器脚本、trace replay、throwaway harness、fuzz、bisect、differential，最后才是 HITL。
-3. 记录 loop 的运行时间、确定性、失败率、症状匹配证据和 sharpen 计划。
-4. 先查 prior investigations、TODOS/backlog、report-card finding 和最近变更。
-5. 先沿代码路径定位触点和最近变更。
-6. 先做 pattern analysis，再列 3-5 个候选假设并收敛到 1-3 个 active hypotheses。
-7. 每个假设都要写支持证据、反证、证伪方法、预期观察、实际观察。
-8. 只有被证据钉死的根因才能进入 repair contract。
-9. repair contract 只讲最小修复边界，不顺手发明新范围。
+1. Reproduce before guessing.
+2. Prove first bad state before naming root cause.
+3. Write only `task.md`; Git records the stage.
+4. No process file beyond `task.md`.
+5. Reroute instead of mixing feature planning into bug investigation.
 
 ## Investigation Modes
 
-| Mode | 什么时候用 | 第一动作 |
-| --- | --- | --- |
-| `reproduce-first` | 症状真实但不稳定 | 缩小复现命令 / 手动路径 |
-| `feedback-loop` | 已有复现但信号慢、松、偶然或不确定是否同一 bug | 记录 loop type、命令、runtime、determinism、failure rate 和 symptom match |
-| `diff-trace` | 昨天可用、今天坏了 | `git log --oneline -20 -- <affected-files>` |
-| `boundary-probe` | API -> service -> DB、CI -> build -> deploy 这类链路断裂 | 记录每层输入、输出、配置和状态 |
-| `backward-trace` | 错误出现在深层堆栈或坏值来源不明 | 从 immediate failure site 反追 original trigger |
-| `reference-compare` | 同仓库有相似可用路径 | 列出 working / broken 差异并逐项接受或排除 |
-| `condition-wait` | flaky、sleep、timeout、重试后消失 | 找真实等待条件，不先加大延时 |
-| `history-trace` | 同一区域反复坏 | 查历史 `planning/analysis.md`、TODO、report-card finding |
-| `pattern-research` | 陌生框架 / 依赖 / 平台错误 | 脱敏后查通用错误类型 |
-| `contract-check` | 修复边界可能扩大 | 判定 implementation drift / missing spec truth / roadmap mismatch |
-| `diagnose-only` | 用户只要问题解释或现在不能修 | 冻结 root cause、owner、risk、next action，不生成实现完成态 |
-| `workflow-forensics` | devflow artifact、git、状态、权限或工具链断裂 | 分类 failure owner 和 rescue action，再决定 reroute |
-
-## Pattern Analysis
-
-至少对照这些模式，不要直接猜：
-
-- race condition：间歇性、时序相关、共享状态
-- null propagation：TypeError / undefined / missing guard
-- state corruption：数据不一致、部分更新、hook / transaction 顺序
-- integration failure：timeout、协议不匹配、外部服务边界
-- configuration drift：本地 / CI / 生产表现不同
-- stale cache：清缓存后恢复或旧状态复现
-- resource leak：OOM、句柄增长、生命周期未释放
-- performance regression：变慢、CPU / IO / 查询耗时升高、吞吐下降
-- trust boundary drift：外部输入、LLM 输出、用户输入被当成可信
-- timing guess / flaky wait：任意 sleep / timeout / setTimeout 掩盖真实条件
-
-性能回归先建 baseline、profiler、query plan 或 bisect，不把普通日志当性能证据。
-
-## Boundary And Trace Evidence
-
-复杂链路必须在 `planning/tasks.md#Root Cause Contract` 写清：
-
-- Boundary Probe Matrix：component boundary、input observed、output observed、config/env observed、state observed、verdict
-- Backward Trace Chain：immediate failure site、caller chain、bad value origin、original trigger、why symptom-site fix is rejected
-- Root Cause Proof Ladder：symptom site、first bad state、violated contract、original trigger、counterfactual proof、escape reason
-- Reference Comparison：similar working example、broken path、differences accepted / ruled out
-- Diagnostic Instrumentation Plan：probe tag、probe location、question answered、command、expected signal、cleanup requirement
-- Feedback Loop Contract：loop type、command、expected / actual signal、symptom match、runtime、determinism、failure rate、sharpening plan
-- Correct Test Seam：test seam、public interface exercised、why it reaches the real trigger chain、why shallow tests are rejected
-- Persistent Debug Session：session id、active hypothesis、completed probes、cleanup state、next evidence action
-- Workflow Forensics：artifact state、git state、runtime state、tool/permission/process failure owner、rescue action
-- Diagnose-Only Outcome：root cause, owner, risk, next action, and explicit no-repair verdict
-
-这些字段不是装饰。它们的作用是证明根因位于源头，而不是报错点。
-
-## Prior Investigation History
-
-形成根因前至少查：
-
-1. `git log --oneline -20 -- <affected-files>`
-2. `rg -n "<error-keyword>|<module>|<capability>" devflow/changes`
-3. `TODOS.md`、backlog、roadmap 中的相关项
-4. 既有 `planning/analysis.md` 和 `review/report-card.json`
-
-命中历史时，写入 `planning/tasks.md#Root Cause Contract` 的 `Prior Investigations`，说明这次是复发、同类结构味道，还是无关历史。
-
-## Domain And Decision Context
-
-优先读取 cc-devflow 原生上下文：`devflow/specs/INDEX.md`、相关 capability specs、roadmap/backlog handoff、历史 `planning/design.md` / `planning/analysis.md`、`change-meta.json`。调查输出里的领域名、假设名、测试名应沿用项目词汇；如果调查结论违反 capability spec、roadmap decision 或历史 design decision，要显式写入 evidence chain，而不是静默覆盖既有设计决策。
-
-## External Research Hygiene
-
-只有在本地证据不足、错误类型陌生、或像依赖 / 框架 / 平台问题时才做外部调研。
-
-- 先删除 host、IP、token、customer id、内部路径、SQL、私有 repo 名。
-- 只搜错误类别、框架 / 库名、版本、通用组件名。
-- 调研结果只能进入候选假设，必须回到本仓库复现或代码证据验证。
-
-## No Code Root Cause
-
-如果结论是环境、外部服务或时序窗口：
-
-- 写 `rootCauseClass`: `code` / `config` / `environment` / `external` / `timing`
-- 写明为什么不是 code root cause
-- 写明需要什么 monitoring / future evidence
-- 写明 operator handling，不要把未知外因包装成代码修复
-
-## Scope Lock
-
-根因假设形成后，写清：
-
-- affected module
-- allowed files
-- forbidden files
-- blast radius estimate
-- if touches >5 files: split / justify / reroute
-
-超过 5 个文件默认是调查信号，不是正常 bug-fix 规模。
-
-## Escalation
-
-三次假设失败后写 `Escalation Decision`：
-
-- failed hypothesis count
-- attempted evidence
-- why current entry is suspect
-- next option：continue / instrument-and-wait / human-review / reroute-cc-plan
-- evidence request：需要可复现环境、HAR、日志 dump、core dump、带时间戳录屏或临时生产探针权限
-- recommendation
-
-## Local Kit
-
-- 默认模板在 `assets/TASKS_TEMPLATE.md` 和 `assets/TASK_MANIFEST_TEMPLATE.json`
-- 旧分析模板在 `assets/legacy/`，只用于 legacy fallback / migration
-- 调查契约在 `references/investigation-contract.md`
-- 需要分析骨架时用 `scripts/bootstrap-analysis.sh`
-- Roadmap 回写使用 `../cc-roadmap/scripts/locate-roadmap-item.sh` 和 `../cc-roadmap/scripts/sync-roadmap-progress.sh`
-
-## Exit Rule
-
-只有当下一位执行者读完 `planning/tasks.md`、`planning/task-manifest.json` 就知道：
+- `reproduce-first`
+- `diff-trace`
+- `boundary-probe`
+- `backward-trace`
+- `condition-wait`
+- `reference-compare`
+- `workflow-forensics`
+- `diagnose-only`
 
-- 为什么坏
-- 该修什么
-- 不该扩到哪里
-- 用什么命令证明修好了
+## Exit
 
-这次调查才算合格。
-如果 source RM 仍然停在旧 status、旧 progress 或旧 REQ/FIX 绑定，说明本次 `cc-investigate` 没有真正退出。
+`task.md` must tell `cc-do` what to fix, what not to touch, and what command proves the repair. Commit the Investigate stage before handing off.

package/.claude/skills/cc-investigate/SKILL.md

@@ -1,72 +1,48 @@
 ---
 name: cc-investigate
-version: 1.5.1
-description: "Use when a bug, regression, broken task, or unexpected behavior needs root-cause investigation, reproducible evidence, and a frozen repair handoff before cc-do resumes coding."
+version: 1.6.1
+description: Use when a bug, regression, broken task, or unexpected behavior needs root-cause investigation before coding resumes.
 triggers:
-  - "帮我查这个 bug"
-  - "先别修先找根因"
-  - "debug this bug"
-  - "investigate this regression"
-  - "why is this broken"
-  - "root cause this"
-  - "先调查再修"
+  - 帮我查这个 bug
+  - 先别修先找根因
+  - debug this bug
+  - investigate this regression
+  - why is this broken
+  - root cause this
 reads:
-  - "PLAYBOOK.md"
-  - "CHANGELOG.md"
-  - "references/investigation-contract.md"
-  - "docs/guides/project-postmortem.md"
-  - "assets/TASKS_TEMPLATE.md"
-  - "assets/TASK_MANIFEST_TEMPLATE.json"
-  - "../cc-roadmap/scripts/locate-roadmap-item.sh"
-  - "../cc-roadmap/scripts/sync-roadmap-progress.sh"
+  - PLAYBOOK.md
+  - references/investigation-contract.md
+  - docs/guides/project-postmortem.md
+  - assets/TASKS_TEMPLATE.md
+  - ../cc-dev/scripts/resolve-cc-devflow.sh
+  - ../cc-roadmap/scripts/locate-roadmap-item.sh
+  - ../cc-roadmap/scripts/sync-roadmap-progress.sh
 writes:
-  - path: "devflow/changes/<change-key>/planning/tasks.md"
-    durability: "durable"
-    required: true
-  - path: "devflow/changes/<change-key>/planning/task-manifest.json"
-    durability: "durable"
-    required: true
-  - path: "devflow/changes/<change-key>/change-meta.json"
-    durability: "durable"
+  - path: devflow/changes/<change-key>/task.md
+    durability: durable
     required: true
 effects:
-  - source roadmap progress sync when investigation freezes, reroutes, or diagnoses a roadmap mismatch
+  - roadmap progress sync when a source item exists
+  - Git commit after the Investigate stage is complete
 entry_gate:
-  - "Read the bug report, existing change artifacts, relevant code/tests/logs, and recent history before forming hypotheses."
-  - "State assumptions, competing interpretations, and what evidence would change the root-cause route before testing hypotheses."
-  - "Assign the change key with `cc-devflow next-change-key --prefix FIX --description \"<short bug name>\"`; first output line is `changeId`, second is full `changeKey`."
-  - "Enforce the Worktree Branch Contract immediately: detached worktrees bind to `FIX/<task>`, default branches stop as setup blockers, unrelated branches need explicit same-change proof."
-  - "Write root-cause truth in `planning/tasks.md#Root Cause Contract`; machine JSON must be generated or refreshed by `cc-devflow task-contract compile`, not handwritten by the AI."
-  - "Build a runnable feedback loop that matches the reported symptom before freezing root cause."
-  - "Search prior investigations, recent fixes, TODO/backlog signals, and project postmortems before declaring the bug novel."
-  - "Run the Root Cause Proof Ladder: symptom site, first bad state, violated contract, original trigger, counterfactual proof, escape reason."
-  - "For multi-component, deep-stack, flaky, or performance symptoms, open the matching escalation pack before declaring root cause."
-  - "Do not write production code here; exit with a frozen repair handoff for cc-do or an explicit reroute."
-  - "Before exit, sync or explicitly no-op the source roadmap item."
+  - Resolve the CLI with `../cc-dev/scripts/resolve-cc-devflow.sh require query workflow-context next-change-key config`.
+  - Assign a FIX change key through `next-change-key --prefix FIX --description "<short bug name>"`.
+  - Enforce the Worktree Branch Contract before writing `task.md`.
+  - Reproduce or build the closest honest feedback loop before naming root cause.
+  - Search relevant code, logs, recent history, and project postmortems before declaring the bug novel.
 exit_criteria:
-  - "`planning/tasks.md#Root Cause Contract` proves the first bad state and original trigger, not only the visible error site."
-  - "`planning/tasks.md#Root Cause Contract` records reproduction, feedback loop, evidence chain, tested hypotheses, confirmed root cause, and repair boundary."
-  - "`planning/tasks.md#Root Cause Contract` records the Project Postmortem Recall result or `no-project-postmortems-yet`."
-  - "`planning/task-manifest.json` and `change-meta.json` were generated or refreshed by `cc-devflow task-contract compile`, then validated."
-  - "`planning/tasks.md` and machine artifacts are explicit enough that cc-do can repair without chat memory."
-  - "`planning/tasks.md` and `change-meta.json` record the canonical work branch or why branch mutation was invalid."
-  - "`cc-devflow query workflow-context --compact` can derive the IDCA next action, packet digest, current task, trusted commands, and deep-open triggers."
-  - "Roadmap sync is updated or a no-op reason is recorded."
-  - "The honest next step is `cc-do`, `cc-plan`, or `roadmap`."
+  - "`task.md#Root Cause Contract` proves symptom site, first bad state, violated contract, original trigger, counterfactual proof, and escape reason."
+  - "`task.md` contains the repair tasks needed by `cc-do`."
+  - "No process file is created beyond `task.md`."
+  - "Source roadmap progress is synced or explicitly skipped in the final response."
+  - "Investigate-stage changes are committed to Git before handing off to `cc-do`."
 reroutes:
-  - when: "The issue is actually a new feature, scope redesign, missing spec truth, or product decision."
-    target: "cc-plan"
-  - when: "The discussion expands into project sequencing or roadmap priority."
-    target: "roadmap"
-  - when: "Root cause and repair boundary are already frozen."
-    target: "cc-do"
-recovery_modes:
-  - name: "repro-reset"
-    when: "The reproduction path is stale, missing, or does not match the reported symptom."
-    action: "Drop the narrative, rebuild the feedback loop from fresh repo evidence, then restate the symptom before testing hypotheses."
-  - name: "re-open-investigation"
-    when: "Execution evidence disproves the current root-cause contract or widens the suspected blast radius."
-    action: "Reopen `planning/tasks.md#Root Cause Contract`, update evidence, then regenerate machine artifacts only after the contract is stable."
+  - when: The issue is actually missing scope, spec truth, or product direction.
+    target: cc-plan
+  - when: Project priority or sequencing is the real question.
+    target: roadmap
+  - when: Root cause and repair boundary are already frozen.
+    target: cc-do
 tool_budget:
   read_files: 8
   search_steps: 5
@@ -75,207 +51,49 @@ tool_budget:
 
 # CC-Investigate
 
-> [PROTOCOL]: 变更时同步更新 `version`、`CHANGELOG.md`、相关模板/脚本引用，然后检查 `CLAUDE.md`
-
-## Role
-
-`cc-investigate` 是 IDCA 的 `Investigate`：把 bug 现象压成证据，把证据压成根因，再把根因压成 `cc-do` 可执行的修复合同。
-
-它不写生产代码，不做产品路线图，不制造调试文档农场。新需求走 `cc-plan`；bug / regression 走 `cc-investigate -> cc-do -> cc-check -> cc-act`。
-
-## Thin Harness Rule
-
-默认相信顶级模型的工程判断。Harness 只守住四件事：
-
-1. 分支、change key、roadmap/source truth 不错位。
-2. 根因证明不能停在 symptom site。
-3. 关键结论落到可恢复 artifact，而不是留在聊天里。
-4. 机器态 JSON 必须由 CLI / 模板生成或更新，AI 不手写过程 JSON。
-
-不要启动就读完所有 reference。先用本文件闭合常规调查；只有触发升级条件时，才打开 `PLAYBOOK.md` 或 `references/investigation-contract.md` 的对应段落。
-
-## Harness Contract
-
-- Allowed actions: reproduce, collect evidence, trace code paths, test hypotheses, freeze root cause in `planning/tasks.md`, run CLI artifact generation, validate, and sync/no-op roadmap.
-- Forbidden actions: production code, guessed root cause, manual JSON authoring, legacy `planning/analysis.md` for new investigations, or symptom patches before root cause proof.
-- Required evidence: every root-cause claim points to reproduction output, code facts, recent history, boundary probes, or explicit user confirmation.
-- Reroute rule: scope/design truth changes go to `cc-plan`; project priority goes to `roadmap`; confirmed repair handoff goes to `cc-do`.
-
-## Investigation Discipline
-
-- Prefer evidence over speed: no reproduction or feedback loop means no confirmed root cause.
-- Use the model for classification and hypothesis ranking; use commands, logs, diffs, and probes for deterministic proof.
-- When evidence conflicts, choose the newer or stronger source and record why the other pattern was rejected.
-- If the bug is really missing spec truth or roadmap mismatch, reroute instead of averaging bugfix and feature design.
-- Any skipped probe, unavailable environment, or stale evidence is an explicit blocker or Evidence Request.
-
-## Runtime Output Policy
-
-写入 durable Markdown 或 metadata 前，先运行：
-
-```bash
-cc-devflow config resolve --format policy
-```
-
-`Output language` 是机器约束，必须记录在 `planning/tasks.md` 和 CLI 生成的 `change-meta.json` 来源字段里。配置解析失败时先修配置或报告阻塞，不用默认语言偷跑。
-
-## Read Lazily
-
-启动时只读：
-
-1. 用户 bug report / failed command / current artifact。
-2. 当前 repo 指令：`CLAUDE.md` / `AGENTS.md` / README 中直接相关部分。
-3. 相关代码、测试、日志、recent diff 的最小证据集。
-4. `assets/TASKS_TEMPLATE.md`。
-
-按需再读：
-
-- `PLAYBOOK.md`：需要完整调查剧本、模式表、边界矩阵、flaky/perf 细则时打开。
-- `references/investigation-contract.md`：要校验字段、hard rules、repair boundary 时打开。
-- `docs/guides/project-postmortem.md`：仓库存在 `devflow/postmortems/` 且匹配历史失败类时打开。
-- `assets/TASK_MANIFEST_TEMPLATE.json`：只在维护模板或对照 CLI 输出结构时打开；普通调查不照抄 JSON。
-- `../cc-roadmap/scripts/*`：定位或回写 source RM 时打开。
-
-## Change Key And Branch
-
-新调查先分配 change key：
-
-```bash
-cc-devflow next-change-key --prefix FIX --description "short bug name"
-```
-
-脚本输出两行：`changeId` 和完整 `changeKey`。直接使用输出，不手动扫描、不心算编号。
-
-分支锚定规则：
+`cc-investigate` 是 IDCA 的 `Investigate`。它把 bug 现象压成根因合同，并把修复边界写入同一个 `task.md`。
 
-1. `FIX-014-auth-race` 对应 `FIX/014-auth-race`。
-2. 当前 detached 时，立刻 `git switch -c <canonical-work-branch>`。
-3. 当前是 `main` / `master` / default branch 时停止，报告 setup blocker。
-4. 当前是其它分支时，只有它已明确绑定同一个 change key 才继续。
+唯一默认输出：
 
-`planning/tasks.md` 和 `change-meta.json` 必须记录 work branch。
+- `devflow/changes/<change-key>/task.md`
 
-## Machine Artifact Rule
+不要生成额外过程文件或 JSON 文档。Git commit 是阶段历史，`task.md` 是根因合同。
 
-AI 只手写默认人类合同：`planning/tasks.md#Root Cause Contract` 和后面的 repair task blocks。
+## Iron Law
 
-机器态文件必须由命令生成或更新：
-
-```bash
-cc-devflow task-contract compile --change <changeId> --change-key <changeKey>
-cc-devflow task-contract validate --change <changeId> --change-key <changeKey>
+```text
+NO REPAIR WITHOUT A FROZEN ROOT-CAUSE CONTRACT
 ```
 
-硬规则：
-
-- 不手写 `planning/task-manifest.json`。
-- 不手写 `change-meta.json`。
-- 不生成 `planning/analysis.md`、task `context.md`、`checkpoint.json`、review Markdown 或其它 AI 手写过程文件。
-- 需要修机器态结构时，改 CLI / 模板 / validator，再重新生成；不要在项目 change 目录里补 JSON。
-- legacy `planning/analysis.md` 只能作为读取或 migration 输入。
+根因不是报错点，而是坏状态第一次被制造的地方。
 
 ## Investigation Loop
 
-1. **Classify**：先说明属于 `reproduce-first`、`feedback-loop`、`diff-trace`、`boundary-probe`、`backward-trace`、`condition-wait`、`workflow-forensics`、`diagnose-only` 还是 reroute。
-2. **Reproduce**：构造 agent 可运行的 pass/fail loop；证明它匹配用户看到的同一个失败。
-3. **Trace**：读代码、测试、日志、recent diff、相关 spec / roadmap / history；找到 first bad state，而不是只看报错点。
-4. **Hypothesize**：列 3-5 个候选，收敛到 1-3 个 active hypotheses；每个都写证伪方法、预期观察、实际观察。
-5. **Prove**：爬完 Root Cause Proof Ladder；缺关键层级时只能写 Evidence Request 或 reroute。
-6. **Freeze**：把根因、边界、测试缝隙、allowed/forbidden files 写进 `planning/tasks.md#Root Cause Contract`。
-7. **Compile**：运行 `cc-devflow task-contract compile` 生成/刷新 manifest 和 meta，再 validate。
-8. **Sync**：定位 source RM，回写调查结果或记录 no-op reason。
+1. Classify：复现优先、diff trace、boundary probe、flaky、performance、workflow forensics 或 diagnose-only。
+2. Reproduce：用测试、脚本、日志、浏览器路径或最小 harness 证明同一个症状。
+3. Trace：找到 first bad state，而不是只给 symptom guard。
+4. Hypothesize：列候选，写证伪方法，逐个打掉。
+5. Prove：完成 Root Cause Proof Ladder。
+6. Freeze：把根因、修复边界、测试 seam、allowed/forbidden files 写进 `task.md`。
+7. Commit：提交 Investigate 阶段，再交给 `cc-do`。
 
 ## Root Cause Proof Ladder
 
-根因不是“报错点在哪里”，而是“坏状态第一次在哪里被制造”。每次调查必须回答：
-
-1. `L1 Symptom Site`：用户看见的错误、失败命令、UI 状态、日志或坏 artifact。
-2. `L2 First Bad State`：第一个字段、文件、缓存、队列消息、API 响应、配置或内存对象从正确变坏的位置。
-3. `L3 Violated Contract`：被破坏的 schema、invariant、API contract、state transition、权限边界或时序条件。
-4. `L4 Original Trigger`：制造 first bad state 的用户动作、命令、事件、recent diff、配置变化或外部响应。
-5. `L5 Counterfactual Proof`：恢复 contract、替换输入、回滚 diff、固定配置或断言边界后的实际观察。
-6. `L6 Escape Reason`：为什么测试、类型、验证、监控、review 或 artifact gate 没提前挡住。
-
-硬规则：
-
-- `First bad state` 为空时，root cause 只能是 `needs-more-evidence`。
-- `Original trigger` 为空时，不能把下游 guard 写成根因修复。
-- `Counterfactual proof` 为空时，假设只能停在 candidate。
-- `Escape reason` 必须变成 regression test、artifact guard、capability invariant、operator check 或明确 follow-up。
-- ladder 指向 spec 缺失或路线假设错误时，reroute 到 `cc-plan` 或 `roadmap`。
-
-## Project Postmortem Recall Gate
-
-形成最终假设前先查项目级 postmortem：
-
-```bash
-rg -n "<symptom|module|boundary|failure-class|model-risk>" devflow/postmortems
-```
-
-- `devflow/postmortems/` 不存在时，在 Root Cause Contract 记录 `no-project-postmortems-yet`。
-- 有命中时读 `INDEX.md` / `principles.md`，再打开最相关的 1-2 个 incident。
-- 相关 incident 必须进入假设表或反证表：同根因、相似症状不同根因、已知模型陷阱或明确不相关。
-- 重复根因必须标记 `recurring` 或 `same-root-cause`。
-
-## Output Model
-
-默认 durable 输出只有 3 个：
-
-1. `planning/tasks.md`
-   - 唯一默认 human-authored Markdown。
-   - `## Root Cause Contract` 记录症状、复现、feedback loop、证据链、Root Cause Proof Ladder、假设、confirmed root cause、repair boundary、correct test seam。
-   - 后续 task blocks 只保留真正要执行的修复任务。
-2. `planning/task-manifest.json`
-   - CLI 生成的执行图真相源。
-   - 不复制调查叙事，不承载 roadmap progress，不手工编辑。
-3. `change-meta.json`
-   - CLI 生成/更新的 change metadata；记录 spec / roadmap / root-cause 摘要和 work branch。
-
-diagnose-only 仍写 `Root Cause Contract`，但 task blocks 只能包含证据交接、监控、人工动作或 reroute，不能伪装成已修复。
-
-## Escalation Packs
-
-只在触发时打开深层规则：
-
-| Pack | Trigger | Open |
-| --- | --- | --- |
-| Boundary Probe | 多组件链路、API/service/DB/queue/build/deploy 边界断裂 | `PLAYBOOK.md#Boundary And Trace Evidence` |
-| Backward Trace | 报错点很深、坏值来源不明、symptom-site guard 看起来诱人 | `references/investigation-contract.md#Backward Trace Chain` |
-| Flaky / Timing | sleep、timeout、重试后消失、低复现率 | `PLAYBOOK.md#Investigation Modes` |
-| Performance | 变慢、CPU/IO/query/throughput 回退 | `PLAYBOOK.md#Pattern Analysis` |
-| External Research | 陌生框架/依赖/平台错误且本地证据不足 | `references/investigation-contract.md#External Research` |
-| No-Code Root Cause | 环境、外部服务、配置或时序窗口 | `references/investigation-contract.md#No Code Root Cause` |
-| Escalation | 三次假设失败或 loop 无法构造 | `references/investigation-contract.md#Escalation` |
-
-如果没有触发条件，不要打开这些包。
-
-## Roadmap Sync
-
-退出前定位 source RM：
-
-```bash
-bash .claude/skills/cc-roadmap/scripts/locate-roadmap-item.sh --id <RM-or-FIX>
-```
-
-- `implementation drift`：回写 source RM 为 repair planned / investigation frozen，绑定 `FIX-*`。
-- `missing spec truth`：写 expected spec delta 或 follow-up，必要时 reroute 到 `cc-plan`。
-- `roadmap mismatch`：写回 roadmap / backlog，下一步是 `roadmap` 或 `cc-plan`，不要直接修。
-- 找不到 source RM 时，在 `planning/tasks.md#Root Cause Contract` 和 `change-meta.json.roadmapSync` 记录 `no-source-rm`。
-
-## Exit Rule
-
-调查合格的标准很简单：
+- L1 Symptom Site
+- L2 First Bad State
+- L3 Violated Contract
+- L4 Original Trigger
+- L5 Counterfactual Proof
+- L6 Escape Reason
 
-- 复现 loop 可信，并匹配用户症状。
-- First bad state、original trigger、counterfactual proof 已冻结。
-- 修复边界清楚到 `cc-do` 不需要二次调查。
-- machine artifacts 由 CLI 生成并通过 validate。
-- source RM 已同步或 no-op reason 已落盘。
+缺 L2、L4 或 L5 时，只能写 Evidence Request、diagnose-only 或 reroute。
 
-如果执行者还要猜“为什么坏、修哪里、不该碰哪里、怎么证明修好了”，调查没完成。
+## Handoff
 
-## Companion Files
+退出时只说清：
 
-- 深入剧本：`PLAYBOOK.md`
-- 变更记录：`CHANGELOG.md`
-- 调查契约：`references/investigation-contract.md`
+- change key 和分支
+- `task.md` 路径
+- 复现 / 证据命令
+- Investigate commit hash
+- 下一步 `cc-do` 或 reroute