cc-devflow 4.5.13 → 4.5.14

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

@@ -1,6 +1,6 @@
 ---
 name: cc-plan
-version: 3.10.1
+version: 3.10.2
 description: Use when a requirement, roadmap item, or bug needs scope clarification, design decisions, and executable task breakdown before coding starts.
 triggers:
   - 帮我规划这个需求
@@ -28,11 +28,14 @@ entry_gate:
   - Resolve the CLI with `../cc-dev/scripts/resolve-cc-devflow.sh require query workflow-context next-change-key config` before workflow commands.
   - Assign a canonical REQ/FIX change key through `next-change-key` before writing `task.md`.
   - Enforce the Worktree Branch Contract immediately after the change key exists.
-  - Read only the repo evidence needed to decide scope, existing leverage, task boundaries, and verification.
-  - Ask only when the answer changes scope, design, implementation boundary, or verification.
+  - Read repo evidence before asking the user: roadmap handoff, specs, relevant code/tests/docs, recent commits, and existing task truth when present.
+  - Run the planning flow before task generation: requirement reality, system shape, interface/data contract, abstraction boundary, execution architecture, task contract, and final approval.
+  - Ask with the Decision Question Protocol when the answer changes scope, design, implementation boundary, or verification.
 exit_criteria:
-  - "`task.md#Contract Summary` states the approved solution, non-goals, frozen decisions, work branch, verification expectations, and open assumptions."
+  - "`task.md#Contract Summary` states the approved solution, non-goals, frozen decisions, work branch, user stories, decision questions, planning-flow results, review gate, verification expectations, and open assumptions."
   - "`task.md` contains executable task blocks generated from `assets/TASKS_TEMPLATE.md`."
+  - "Non-trivial plans compare `minimal viable` and `ideal architecture` before approval."
+  - "User decisions that changed the plan were asked as D<N> questions and recorded in `task.md`."
   - "No process file is created beyond `task.md`."
   - "Source roadmap progress is synced or explicitly skipped in the final response."
   - "Plan-stage changes are committed to Git before handing off to `cc-do`."
@@ -53,15 +56,15 @@ tool_budget:
 
 - `devflow/changes/<change-key>/task.md`
 
-不要生成额外过程文件或 JSON 文档。Git commit 是阶段历史，`task.md` 是任务真相。
+不要生成额外过程文件。Git commit 是阶段历史，`task.md` 是任务真相。
 
 ## Operating Contract
 
 1. 先用 resolver 找到当前仓库的 `cc-devflow`，并确认支持 `query workflow-context`、`next-change-key`、`config`。
 2. 用 `next-change-key --prefix REQ|FIX --description "..."` 生成 `changeId` 和完整 `changeKey`，不要手动扫描编号。
 3. 分配 change key 后立刻锚定分支：`REQ-003-copy-link` 对应 `REQ/003-copy-link`，`FIX-014-auth-race` 对应 `FIX/014-auth-race`。当前在 default branch 时停止并报告 setup blocker。
-4. 写 `task.md` 前先确认方案。tiny 计划仍要被批准，只是更短。
-5. `task.md` 必须包含 `Contract Summary`、任务列表、验证命令、完成证据、禁止重决策事项和阶段 commit 要求。
+4. 写 task blocks 前先确认方案。tiny 计划仍要过 planning flow，只是更短。
+5. `task.md` 必须包含 `Contract Summary`、决策问题、planning flow、review gate、任务列表、验证命令、完成证据、禁止重决策事项和阶段 commit 要求。
 6. 完成 Plan 后提交 Git commit。下一阶段从 Git history 和 `task.md` 恢复，不靠过程文件。
 
 ```bash
@@ -74,10 +77,67 @@ bash "$DEVFLOW" config resolve --format policy
 - 用最小可逆方案解决真实需求，不扩张到假想未来。
 - 缺证据就写 assumption，不伪装成事实。
 - 非 trivial 方案比较 `minimal viable` 和 `ideal architecture`，但推荐必须落到当前仓库可执行边界。
+- 计划先做上下文和设计判断，再拆 task；不能把架构、接口、字段、测试缝隙留给 `cc-do` 猜。
+- 用户视角必须清楚：真实用户 / operator、status quo、最痛失败场景、最小成功信号和非目标。
 - 行为变更任务按 tracer bullet 写：`[TEST] -> [IMPL] -> [REFACTOR]`，不要水平切层。
 - 每个任务写清目标、文件、依赖、TDD phase、读什么、怎么验证、完成证据。
 - 回归测试不能 defer；缺 seam 时先计划 spike 或设计修正。
 
+## Planning Flow
+
+先把调查和引导结果写进 `task.md#Contract Summary`，再生成任务。不要把这些内容拆成其它过程文件。
+
+1. Requirement Reality：确认真实用户 / operator、当前 workaround、最痛失败场景、最小成功信号、非目标。
+2. System Shape：确认现有代码链路、模块归属、状态 / 数据流、复用点、边界外系统和必须保留的不变量。
+3. Interface / Data Contract：确认 public interface、调用方、输入输出、关键字段、错误形态、权限 / 边界和命名来源。
+4. Abstraction Boundary：确认复杂度藏在哪个模块，哪些抽象被拒绝，哪些公共方法必须保持小而深。
+5. Execution Architecture：确认 foundation、core logic、integration、polish/tests 阶段的冻结决策、文件职责、耦合风险和失败恢复。
+6. Task Contract：确认每条 tracer bullet 的 user / edge story、Red test name、public seam、Green minimality guard、refactor candidates 和 2-5 分钟任务粒度。
+7. Final Approval：展示冻结方案和任务合同摘要；用户批准前不生成执行 task blocks。
+
+`tiny-design` 可以把每轮压成一句话；`full-design` 必须保留足够证据让执行者不二次设计。任一轮 `blocked` 时，只能问一个 blocking question、拆回 roadmap / 多个 REQ/FIX，或记录用户明确接受的人工边界。
+
+## Decision Question Protocol
+
+只在答案会改变范围、方案、接口、任务切分或验证口径时提问。能从 repo evidence、roadmap、spec、测试或 git history 确认的，不问用户。
+
+固定格式：
+
+```text
+D<N> - <decision title>
+Planning object: <REQ/FIX/RM/change key>
+Known evidence: <repo / roadmap / code / test facts>
+Decision needed: <what changes downstream>
+Recommendation: <A/B/C> because <reason>
+Options:
+A) <label> (recommended)
+  Good: <upside>
+  Cost/Risk: <cost or risk>
+B) <label>
+  Good: <upside>
+  Cost/Risk: <cost or risk>
+C) <label, optional>
+  Good: <upside>
+  Cost/Risk: <cost or risk>
+Impact: <what cc-do will do differently>
+STOP: wait for the user answer before continuing.
+```
+
+用户回答后，把决定写入 `task.md#Contract Summary` 的 `Decision Questions`。聊天不是长期真相源。
+
+## Engineering Review Gate
+
+冻结 task blocks 前，在 `task.md#Contract Summary` 里完成轻量 review：
+
+1. Existing leverage map：每个子问题先映射到现有代码、脚本、spec、模板或测试。
+2. Scope challenge：超过 8 个文件、2 个新 service/class、或跨模块连锁时，说明为什么不是过度设计。
+3. Option role check：非 trivial 方案比较 `minimal viable`、`ideal architecture`，必要时加 `hybrid`。
+4. Domain language check：核心名词、文件名、测试名、任务标题对齐项目真相；没有来源就写 assumption。
+5. Interface depth check：公共面小而深，复杂度藏进模块内部，边界 adapter 是具体操作而不是 generic catch-all。
+6. Test seam check：Red 任务从公共接口、调用方流程或用户可见路径证明行为；不要测私有实现细节。
+7. Mock boundary check：只 mock 外部 API、时间、随机性、文件系统或必要数据库边界。
+8. Feedback loop check：为每个行为选定最短可信反馈循环。
+
 ## Required Output
 
 `task.md` 的结构由 `assets/TASKS_TEMPLATE.md` 提供。模板外只允许补充对当前需求必要的事实，不允许新建额外过程文件。

package/.claude/skills/cc-plan/assets/TASKS_TEMPLATE.md

@@ -20,9 +20,57 @@ Goal:
 Do Not Do:
 -
 
+Source Handoff:
+- Roadmap / issue / user source:
+- Repo evidence read:
+- Existing leverage:
+- Canonical language:
+
+Requirement Reality:
+- User / operator:
+- Status quo workaround:
+- Most painful failure:
+- Smallest success signal:
+- Non-goals:
+
+Decision Questions:
+| ID | Decision | Evidence | Choice | Impact |
+|----|----------|----------|--------|--------|
+| D1 |  |  |  |  |
+
+Planning Flow:
+| Round | Status | Evidence / decision | Opens task? |
+|-------|--------|---------------------|-------------|
+| Requirement Reality | confirmed |  |  |
+| System Shape | confirmed |  |  |
+| Interface / Data Contract | confirmed |  |  |
+| Abstraction Boundary | confirmed |  |  |
+| Execution Architecture | confirmed |  |  |
+| Task Contract | confirmed |  |  |
+| Final Approval | confirmed |  | yes |
+
+Options:
+- Minimal viable:
+- Ideal architecture:
+- Recommended:
+- Why not the other option:
+
 Approved Direction:
 -
 
+User Stories:
+| ID | Actor | Story | Acceptance | Edge / recovery |
+|----|-------|-------|------------|-----------------|
+| US-001 |  |  |  |  |
+
+Engineering Review Gate:
+- Existing leverage map:
+- Scope challenge:
+- Interface depth:
+- Test seam:
+- Mock boundary:
+- Feedback loop:
+
 Acceptance:
 -
 

package/.claude/skills/cc-plan/references/planning-contract.md

@@ -9,9 +9,28 @@
 5. New change keys come from `cc-devflow next-change-key`.
 6. Branch binds to the full change key before durable output.
 7. User decisions that affect scope, design, or verification are written into `task.md#Contract Summary`.
-8. Placeholder tasks are invalid.
-9. Behavior work uses tracer bullets and TDD unless an exception is recorded.
-10. Roadmap sync, when needed, happens through roadmap files and Git commit, not change metadata.
+8. Planning flow results are written into `task.md#Contract Summary`; removing old process files must not remove planning thought.
+9. Placeholder tasks are invalid.
+10. Behavior work uses tracer bullets and TDD unless an exception is recorded.
+11. Roadmap sync, when needed, happens through roadmap files and Git commit, not change metadata.
+
+## Planning Flow
+
+Every non-trivial plan confirms these rounds before task generation:
+
+1. Requirement Reality: real user/operator, workaround, painful failure, smallest success signal, non-goals.
+2. System Shape: existing code path, module owner, state/data flow, reuse point, boundary systems.
+3. Interface/Data Contract: public seam, caller, input/output, fields, error shape, permission/boundary.
+4. Abstraction Boundary: where complexity lives, rejected abstractions, public/private method split.
+5. Execution Architecture: foundation/core/integration/polish decisions, file responsibility, failure recovery.
+6. Task Contract: tracer bullets, Red test names, public seams, Green minimality, refactor candidates.
+7. Final Approval: approved option and task contract summary.
+
+Tiny plans may compress a round to one evidence-backed line. Full designs must preserve enough detail that `cc-do` does not invent architecture, fields, interfaces, or tests.
+
+## Decision Questions
+
+Ask only when the answer changes scope, design, task split, interface, or verification. Use `D<N>` with known evidence, recommendation, 2-3 mutually exclusive options, impact, and a stop point. Record the answer in `task.md#Contract Summary`.
 
 ## Required Task Fields
 
@@ -28,4 +47,4 @@
 
 ## Review Gate
 
-Before exit, check scope, existing leverage, non-goals, ambiguity, test seam, mock boundary, and failure modes. If the plan is not executable from `task.md`, it is not done.
+Before exit, check scope, existing leverage, option role, domain language, interface depth, test seam, mock boundary, feedback loop, and failure modes. If the plan is not executable from `task.md`, it is not done.

package/.claude/skills/cc-review/CHANGELOG.md

@@ -1,5 +1,11 @@
 # CC-Review Changelog
 
+## 2.2.1 - 2026-05-14
+
+- restore deep review method flow without restoring review process files
+- add node-by-node review, risk-lane coverage, finding aggregation, decision question, plan facet, implementation diff, and test-quality guidance
+- keep plan review output in `task.md` and implementation review output in the response/user-choice loop
+
 ## 2.2.0 - 2026-05-13
 
 - split review exits by branch: plan and investigation reviews write findings directly into `task.md`

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

@@ -11,9 +11,12 @@
 3. 不读取、不生成、不维护过程文件。
 4. Git history 是唯一持久 review 记忆；重复 review 时用 `git diff <old>...HEAD` 缩小范围。
 5. 可用 subagent 时可以派发只读 reviewer；raw output 留在会话里，主线程验证后再进入最终 findings。
-6. 不固定 finding 数量。证据决定输出。
-7. 每条 finding 必须有 evidence、impact、recommendation 和 route。
-8. 计划 review 的结果直接写回 `task.md`；执行 review 的结果先询问用户选择修复方案；只差验收，进 `cc-check`。
+6. 复杂实现或 mixed review 考虑 intent/regression、security/privacy、performance/reliability、contracts/coverage 四类风险 lane。
+7. 按 selected facet 或 changed surface 逐节点检查；每个节点 checked、skipped 或 blocked。
+8. 不固定 finding 数量。证据决定输出。
+9. 每条 finding 必须有 evidence、impact、recommendation 和 route。
+10. 输出前聚合 raw findings：合并重复，降级弱证据，拒收 speculative / out-of-scope / stale findings。
+11. 计划 review 的结果直接写回 `task.md`；执行 review 的结果先询问用户选择修复方案；只差验收，进 `cc-check`。
 
 ## Review Standard
 
@@ -26,6 +29,9 @@
 - 哪些代码坏味道在当前 blast radius 内？
 - 哪些测试、日志、UI 操作或端到端证据缺失？
 - 哪些 finding 必须修，哪些可以 defer，哪些只是 advisory？
+- 哪些节点已经审过，哪些 skipped / blocked，原因是什么？
+- 四类风险 lane 哪些覆盖了，哪些因为 scope 小或工具不可用跳过？
+- subagent findings 哪些被接受、合并、降级或拒收？
 - 下一步为什么是 `cc-plan` / `cc-do` / `cc-check` / `cc-act` / `stop`？
 
 ## Decision Rule

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

@@ -1,6 +1,6 @@
 ---
 name: cc-review
-version: 2.2.0
+version: 2.2.1
 description: Use when a plan, bug fix, PR, or implementation diff needs review findings. Plan reviews write findings into task.md; implementation reviews ask the user to choose a repair option before fixing.
 triggers:
   - 深度 review 这个方案
@@ -17,6 +17,7 @@ reads:
   - references/plan-review-branch.md
   - references/implementation-review-branch.md
   - references/e2e-and-plugin-verification.md
+  - scripts/collect-review-context.sh
 writes:
   - path: current response
     durability: ephemeral
@@ -34,6 +35,7 @@ entry_gate:
   - Classify the review target as plan, implementation, PR, or mixed.
   - Read only the task, PR, diff, code, tests, logs, screenshots, and docs needed to review the requested scope.
   - Use Git history and current diff as the only durable review memory; do not load or create process files.
+  - For repeat reviews, use `git diff <old>...HEAD` or `scripts/collect-review-context.sh` to narrow the delta before re-reviewing.
   - Freeze the requested scope before finding smells; report only issues inside the change blast radius or clearly amplified by it.
   - Subagents are optional read-only reviewers; their raw output stays in the conversation and is not saved to files.
 exit_criteria:
@@ -42,6 +44,8 @@ exit_criteria:
   - Plan or investigation review findings are written into the relevant `task.md` section before exit.
   - Implementation review findings are returned with concrete repair options and a blocking user choice; no repair happens until the user selects an option.
   - In-scope code smells are either findings, explicit defers, or clean with reason.
+  - Selected review facets or changed surfaces are checked, skipped with reason, or blocked; no artificial finding cap was applied.
+  - Subagent findings, when used, are accepted, merged, downgraded, or rejected by the main thread before final output.
   - If no issues are found, the answer says so and names residual test or evidence risk.
   - No process file was created.
 reroutes:
@@ -97,6 +101,21 @@ Review 的价值在于问题质量，不在于过程记录数量。没有证据
 | `PR` | 用户要求 review PR | PR diff, body accuracy, CI/test proof, merge risk |
 | `mixed` | 方案和实现都变了 | plan contract first, then implementation conformance |
 
+## Review Loop
+
+每次 review 都保留深度流程，但不保留过程文件：
+
+1. Classify：判断 plan / implementation / PR / mixed。
+2. Scope Freeze：写清本次 review 的意图、blast radius、明确不审的历史债。
+3. Delta：用 Git、PR diff、`task.md` 和当前命令输出确定相对上次或 base 的真实变化。
+4. Facets：按风险选择 strategy / engineering / design / DX / TOC / contract / smell / test / runtime / docs。
+5. Nodes：把每个 selected facet 或 changed surface 当成一个 review node，在 scratch reasoning 中逐个检查；每个 node 只能 checked、skipped、blocked。
+6. Findings：每个 finding 必须有 evidence、impact、recommendation、route；没有证据的怀疑只能是 residual risk 或 blocked evidence。
+7. Aggregate：合并重复 finding，降级弱证据，拒收 out-of-scope、stale、speculative finding。
+8. Exit：计划问题写 `task.md`；实现问题回对话给修复选项；只差验证进 `cc-check`。
+
+渐进加载只控制读多少上下文，不允许把该审的节点省掉。
+
 ## Exit Contract
 
 - Plan / investigation review: directly update `devflow/changes/<change-key>/task.md` with the review findings, decision options, blocked assumptions, and required task changes. Final response only summarizes what was written and the next route.
@@ -104,6 +123,17 @@ Review 的价值在于问题质量，不在于过程记录数量。没有证据
 - PR review: return findings in the response or GitHub review only; do not write local files.
 - Clean review: say `No findings`, name residual verification risk, and route to `cc-check` or `stop`.
 
+## Risk Lanes
+
+复杂实现、跨模块 diff、PR landing 前复审、或 mixed review 默认考虑四条风险 lane。小 diff 可以由一个 combined pass 覆盖，但必须说明 skip reason。
+
+1. Intent / regression: diff 是否兑现意图，是否引入范围外行为、fallback 退化、caller/callee contract 漂移。
+2. Security / privacy: auth、输入验证、注入、secret、敏感数据、默认权限、外部输入信任边界。
+3. Performance / reliability: 热路径重复 I/O、启动/渲染/请求成本、cleanup 泄漏、retry storm、排序/竞态、失败处理。
+4. Contracts / coverage: API/schema/type/config/flag、迁移 fallout、回归测试、日志、metrics、assertion、error path。
+
+这些是审查视角，不是 finding 配额。
+
 ## Finding Rules
 
 每条 finding 必须包含：
@@ -121,6 +151,27 @@ Review 的价值在于问题质量，不在于过程记录数量。没有证据
 
 可以使用只读 reviewer subagent，但输出只在主线程汇总，不写文件。主线程必须验证、去重、降级或拒收 subagent finding。
 
+Subagent 只拿自己的 review packet：scope、delta、node/facet、需要读取的文件、输出格式。不要把完整聊天历史当作 reviewer 上下文。没有 subagent 工具时，主线程按同样 node/facet 串行检查，并在输出中说明 fallback。
+
+## Decision Questions
+
+只有 finding 需要用户判断时才提问。不要在第一个问题处打断整个 review，除非答案会阻塞下一个 node。
+
+格式：
+
+```text
+D<N> - <decision title>
+Evidence: <file/line/diff/log/UI action>
+Risk: <what breaks if ignored>
+Recommendation: <recommended option and why>
+Options:
+A) <smallest safe fix> - impact
+B) <broader cleanup> - impact
+C) <defer> - risk
+```
+
+Plan / investigation review 的 decision question 写进 `task.md`。Implementation review 的 repair options 留在当前回复，等待用户选择。
+
 ## Output
 
 按 review 类型输出：

package/.claude/skills/cc-review/references/implementation-review-branch.md

@@ -1,12 +1,112 @@
 # Implementation Review Branch
 
-Read:
+Use this reference when the review target is code, tests, docs, UI behavior, or a current branch diff.
 
-1. current Git diff
-2. `task.md`
-3. changed code and tests
-4. fresh command output when available
+## Intake
 
-Review behavior, regression risk, security, reliability, test quality, and code smells inside the current blast radius.
+Read, in order:
+
+1. current branch and base branch
+2. `git diff <base>...HEAD --stat`
+3. full diff for changed files
+4. `task.md`
+5. changed code plus direct importers/callers for enum, state, API, and behavior changes
+6. fresh command output when available
+
+If no plan exists, infer intent from user request, commits, TODOs, and PR body if present. Mark intent confidence.
+
+## Scope Check
+
+Produce this in scratch reasoning before findings:
+
+```text
+Scope Check: CLEAN | DRIFT DETECTED | REQUIREMENTS MISSING
+Intent: ...
+Delivered: ...
+Diff surface: ...
+```
+
+Out-of-scope files are findings only when they change behavior or expand blast radius.
+
+## Diff Review Passes
+
+Turn these passes into review nodes before reporting findings. Every changed file, public behavior, test surface, documentation surface, and UI/runtime flow belongs to a node or has a skip reason.
+
+For broad or PR-landing diffs, use the risk-lane profile from `review-methods.md` before final findings:
+
+1. Intent and regression
+2. Security and privacy
+3. Performance and reliability
+4. Contracts and coverage
+
+### Contract Fidelity
+
+Check whether implementation matches `task.md` or investigation:
+
+- required tasks done
+- rejected scope not implemented
+- root cause still true
+- expected spec delta honored
+- behavior visible at public seam
+
+### Code Smell Scan
+
+Use `review-methods.md` smell taxonomy.
+
+Look for:
+
+- copy-paste helper logic
+- broad catch-all errors
+- parameter clumps
+- shallow pass-through modules
+- internal mocks driving production design
+- new branch forests where a data shape would collapse cases
+- hidden state or multiple truth sources
+- cycles between modules
+
+### Structural Risk
+
+Check:
+
+- security and trust boundaries
+- enum/value completeness outside the diff
+- migrations and rollback
+- concurrency and double-submit
+- external service failures
+- logs/metrics for new paths
+
+### Test Quality
+
+Build a coverage map:
+
+```text
+CODE PATHS                         USER/RUNTIME FLOWS
+file.ts                            feature flow
+├── [tested] happy                 ├── [tested] main path
+├── [gap] empty                    ├── [gap] double action
+└── [gap] upstream error           └── [gap] navigate away / timeout
+```
+
+Flag:
+
+- no regression test for changed behavior
+- tests only assert implementation shape
+- tests mock internal modules instead of public seam
+- fixture lies with missing fields or type casts
+- no UI/E2E proof for user-visible change
+
+### Documentation and DX
+
+If changed behavior affects README, guides, CLI help, package install, public API, agent skill usage, or examples, check whether docs changed too.
+
+## Fix Policy
 
 Findings stay in the response. Ask which repair option to apply before editing code. Do not write process files.
+
+Return:
+
+- findings ordered by severity
+- smallest safe repair option
+- broader cleanup option when the smell is real
+- defer option with explicit risk
+- recommendation and route

package/.claude/skills/cc-review/references/plan-review-branch.md

@@ -1,9 +1,114 @@
 # Plan Review Branch
 
-Read:
+Use this reference when the review target is a plan, investigation handoff, or mixed branch whose plan contract may be wrong.
+
+## Intake
+
+Read, in order:
 
 1. `task.md`
-2. relevant roadmap or issue text
-3. affected code/tests/docs
+2. relevant roadmap, issue, PR text, or user request
+3. affected code/tests/docs referenced by the plan
+4. existing command output only when it proves or disproves a planning assumption
+
+If no `task.md` exists, review the user-provided plan text and make missing durable task contract a finding.
+
+## Review Facets
+
+Select only applicable facets, but do not skip a selected facet to keep the answer short.
+
+### Strategy
+
+Check:
+
+- Is this the right problem?
+- Is the stated user/business outcome direct or only a proxy?
+- What happens if we do nothing?
+- What does the 12-month ideal look like?
+- What existing code or workflow already solves part of this?
+
+Useful shape:
+
+```text
+CURRENT -> THIS PLAN -> 12-MONTH IDEAL
+```
+
+### Engineering
+
+Check:
+
+- component boundaries
+- data flow and shadow paths
+- state transitions
+- security boundaries
+- rollback shape
+- testability seam
+- parallelization risk
+
+For non-trivial plans, reason through:
+
+```text
+Entry -> validate -> transform -> persist -> output
+  |        |            |            |          |
+ nil     invalid      exception    conflict   stale
+ empty   wrong type   timeout      duplicate  partial
+```
+
+### Design
+
+Run only for user-facing UI or interaction flows.
+
+Check:
+
+- first, second, third thing the user sees
+- loading / empty / error / success / partial states
+- responsive and accessibility intent
+- generic UI or AI slop risk
+- whether live design review will be needed after implementation
+
+### DX / Operator
+
+Run only for API, CLI, SDK, package, docs, agent skill, MCP, or developer/operator surfaces.
+
+Check:
+
+- target developer/operator persona
+- time to first value
+- install/run/debug/upgrade path
+- actionable errors: problem + cause + fix
+- copy-paste examples and escape hatches
+
+### TOC Root Cause
+
+For complex bugs:
+
+1. Current reality tree: symptoms, causes, enabling conditions.
+2. Conflict diagram: why the obvious fix conflicts with a real need.
+3. Future reality tree: what the proposed fix changes and what it may break.
+
+If the root cause is not proven, reroute to `cc-investigate`, not `cc-do`.
+
+## Planning Smells
+
+Plans can contain smells before code exists:
+
+- repeated implementation steps with slight variations
+- parallel data sources
+- task split by technical layer instead of behavior
+- fake abstraction or one-adapter seam
+- missing owner for shared state
+- hand-wavy "handle edge cases" or "add validation"
+
+Each planning smell becomes a finding in `task.md` and routes to `cc-plan`.
+
+## Output
+
+Write plan review findings directly into `task.md`:
+
+- scope or architecture finding
+- evidence and impact
+- required task or contract change
+- decision options when user judgment is needed
+- reroute recommendation
 
-Find scope, architecture, test-strategy, and ambiguity problems. Write findings into `task.md`; final response only summarizes the changed sections. Do not write separate files.
+Final response only summarizes changed `task.md` sections and next route. Do not write separate files.