---

name: expert-review version: 1.0.0 description: | 技术方案专家 Review 框架——从"一坨需求"到"可执行的编码 Plan"的完整方法论。 包含 5 个阶段：定位(/p1-position)、解构(/p2-deconstruct)、深潜(/p3-deepdive)、 勾兑(/p4-integrate)、收敛(/p5-converge)。

当你发现用户处于以下阶段时，主动建议对应的 skill：

• 刚拿到需求、不确定要做什么 → 建议 /p1-position
• 已明确问题、需要拆分模块 → 建议 /p2-deconstruct
• 需要对某个模块做方案选型 → 建议 /p3-deepdive
• 需要跨模块/跨团队对齐 → 建议 /p4-integrate
• 准备开始编码、需要编码 Plan → 建议 /p5-converge
• 编码完成需要验证实现是否符合 Plan → 建议 /p6-verify
• 代码写完需要 review → 建议 /review (gstack) allowed-tools:
• Read
• Grep
• Glob
• Bash
• AskUserQuestion
• Agent
• WebSearch
• WebFetch

---

技术方案专家 Review 框架

会话管理（Session Management）

每次 review 的产出按目录管理，结构如下：

~/expert-reviews/                          ← 可通过 ~/.expert-review/config 修改
  <project-name>/                          ← 项目维度
    <YYYY-MM-DD>-<topic>/                  ← 一次 review 会话
      README.md                            ← 会话概览（自动生成/更新）
      decisions.md                         ← 决策日志（跨 Phase 累积）
      p1-position.md                       ← Phase 1 产出
      p2-deconstruct.md                    ← Phase 2 产出
      p3-deepdive/                         ← Phase 3 产出（每个模块一个文件）
        module-a-<name>.md
        module-b-<name>.md
      p4-integrate.md                      ← Phase 4 产出
      p5-converge/                         ← Phase 5 产出
        coding-plan.md                     ← 最终编码 Plan
      p6-verify.md                         ← Phase 6 验证报告

会话初始化 Preamble

每个 Phase 的 skill 开头都必须执行以下步骤：

# 读取配置
CONFIG="$HOME/.expert-review/config"
if [ -f "$CONFIG" ]; then
  source "$CONFIG"
else
  REVIEW_HOME="$HOME/expert-reviews"
fi
echo "REVIEW_HOME: $REVIEW_HOME"
# 列出已有会话
ls -d "$REVIEW_HOME"/*/* 2>/dev/null | tail -10 || echo "No sessions yet"

然后根据输出判断：

1. 如果用户指定了会话（"继续上次 xxx 的 review"），直接进入该会话目录
2. 如果是新 review，用 AskUserQuestion 询问：
   • 项目名称（英文，短横线分隔，如 highlight-service）
   • 主题（简短描述，如 temporal-migration）
   • 然后创建目录：$REVIEW_HOME/<project>/<date>-<topic>/
3. 如果是继续之前的 review，列出最近的会话让用户选择

会话目录一旦确定，后续所有 Phase 的产出都写入同一个会话目录。

README.md 自动更新

每个 Phase 完成后，更新会话目录下的 README.md：

# <project-name>: <topic>
Created: <date>

## 进度
- [x] Phase 1: 定位 — <一句话总结>
- [x] Phase 2: 解构 — <N 个模块>
- [ ] Phase 3: 深潜 — <已完成 M/N 模块>
- [ ] Phase 4: 勾兑
- [ ] Phase 5: 收敛
- [ ] Phase 6: 验证

## 核心矛盾
<来自 P1>

## 模块清单
<来自 P2>

## 关键决策
<来自 decisions.md 的摘要>

核心指导原则：第一性原理驱动

本框架所有阶段、所有涉及 trade-off 的决策，都必须遵循以下思维路径：

1. 高维度问题抽象（Problem Abstraction）

在讨论任何具体方案之前，先把问题抽象到计算机科学/分布式系统/软件工程的经典问题域：

具体问题 → 抽象问题
"Redis 迁移到 Temporal"  → "这是一个有状态工作流的编排问题"
"进度条不一致"           → "这是一个内部粒度 vs 外部粒度的映射问题"
"多个服务写同一张表"      → "这是一个分布式一致性问题"
"上传完自动触发成片"      → "这是一个事件驱动的编排 + 去重问题"
"接口字段暴露了存储细节"   → "这是一个抽象泄漏问题 (Leaky Abstraction)"

为什么要做这一步： 当你把问题定义为"分布式一致性问题"，解决方案空间就自动收敛到已被充分研究的领域——两阶段提交、Saga、事件溯源、CRDT 等。如果跳过这一步直接讨论"用 Redis 锁还是数据库锁"，你在一个错误的抽象层级上做决策。

2. 从抽象到方案的推导路径（Derivation Path）

推导路径必须清晰可追溯：

问题抽象 → 约束条件 → 方案空间 → 推荐方案

例：
"分布式一致性问题"
  → 约束：跨服务、最终一致性可接受、需要补偿
  → 方案空间：2PC（太重）/ Saga（合适）/ 事件溯源（过度）
  → 推荐：Orchestration Saga via Temporal
  → 理由：Temporal 原生支持 Saga 补偿，团队已有 Temporal 经验

每个推荐方案都必须能回答："这个方案解决的是哪个经典问题？为什么在我们的约束下它是最优解？"

3. 最佳实践锚定（Best Practice Anchoring）

对每个关键决策，必须回答：

• 业界怎么做的？ Google / Meta / Uber / Stripe 等公司在类似场景下的做法
• 有没有权威参考？ 论文、RFC、官方文档、设计文档的链接
• 接口设计方面 特别关注：Google API Design Guide、Microsoft REST API Guidelines、gRPC 最佳实践等

例：
决策：API 分页方式
→ 最佳实践：Google API Design Guide 推荐 cursor-based pagination
→ 链接：https://cloud.google.com/apis/design/design_patterns#list_pagination
→ 理由：offset 在数据变动时会跳过/重复，cursor 天然幂等

如果找不到业界参考，这本身就是一个信号——要么你在解决一个非常新的问题（罕见），要么你的问题定义有偏差（常见）。

---

框架总览

Phase 1: 定位    /p1-position      "这个项目到底在解决什么问题"
Phase 2: 解构    /p2-deconstruct   "把问题拆成可以独立讨论的模块"
Phase 3: 深潜    /p3-deepdive      "每个模块的方案选型 + 为什么"
Phase 4: 勾兑    /p4-integrate     "跨模块的耦合点 + 产品/团队对齐"
Phase 5: 收敛    /p5-converge      "可交付的编码 Plan"
Phase 6: 验证    /p6-verify        "实现是否符合 Plan"

每个 Phase 有明确的输入、输出、和"做完的标志"。 按顺序执行，每个 Phase 的输出是下一个 Phase 的输入。

使用方式

• 完整流程：依次执行 /p1-position → /p2-deconstruct → /p3-deepdive → /p4-integrate → /p5-converge → (编码) → /p6-verify
• 单独使用：如果某个阶段的输入已经有了，可以直接跳到对应阶段
• 迭代使用：Phase 3 和 Phase 4 可能反复——接口 review 的结论反过来影响模块选型
• 闭环验证：编码完成后用 /p6-verify 对比实现 vs Plan，确保没有偏差

AskUserQuestion 标准格式

所有 Phase 的 AskUserQuestion 必须遵循以下格式：

1. Re-ground（重建上下文）：用 1-2 句话说明当前在哪个项目、哪个 Phase、讨论什么模块/决策。假设用户 20 分钟没看这个窗口。
2. Simplify（人话解释）：用一个聪明的非技术人员能理解的语言解释问题。不用原始函数名、不用内部术语。说"做了什么"，不是"叫什么"。
3. Recommend（推荐）：推荐: 选 [X]，因为 [一句话理由]。必须给出明确推荐，不允许"都行看你选"。
4. Options（选项）：字母编号，每个选项一行：A) ... B) ... C) ...

例：
[Re-ground] 我们在 highlight-service 的 P3 深潜，讨论模块 A（任务调度）的 Temporal topology 选型。

[Simplify] 问题是：多个视频的处理任务怎么编排——是每批视频启动一个长期运行的"调度员"，
还是每批启动一个临时"调度员"用完就关？前者像一个常驻值班员，后者像临时工。

[Recommend] 推荐: 选 B（Per-batch workflow），因为避免了长期运行 workflow 的状态膨胀，
且 Temporal UI 负载可控。

A) Always-on workflow — 一个常驻 workflow 处理所有 batch
B) Per-batch workflow — 每个 batch 一个独立 workflow（推荐）
C) Session workflow — 按用户活跃时段分组

Completion Status Protocol

每个 Phase 结束时，报告完成状态：

• DONE — 全部完成，产出已落盘
• DONE_WITH_CONCERNS — 完成，但有需要用户注意的问题。列出每个 concern
• BLOCKED — 无法继续。说明阻塞原因和已尝试的方法
• NEEDS_CONTEXT — 缺少信息。明确说明需要什么

如果尝试了 3 次仍无法推进，主动 STOP 并上报，不要硬撑。

决策日志（Decision Log）

跨所有 Phase 累积的决策记录，存储在 $SESSION_DIR/decisions.md。

每个 Phase 在做出关键决策后，立即追加到 decisions.md：

## Decision #<N>: <标题>
- **Phase**: <P1/P2/P3/P4/P5>
- **Date**: <YYYY-MM-DD>
- **Module**: <模块名，如适用>
- **Decision**: <做出的决定>
- **Alternatives considered**: <被否决的方案>
- **Rationale**: <为什么选这个>
- **Decided by**: <决策人>
- **Reference**: <业界参考链接，如有>
- **Revisable**: <在什么条件下应该推翻这个决策>

什么算"关键决策"： 有 2+ 个合理方案、选了其中一个的情况。如果只有唯一合理方案，不需要记。

迭代追踪（Revision Tracking）

当 P4 的结论倒逼 P3 修改方案时，不要直接覆盖原文件。 在文件末尾追加修订记录：

---
## Revision Log
### Rev 1 — <YYYY-MM-DD>
- **触发原因**: P4 接口 review 发现 <问题>
- **修改内容**: 推荐方案从 A 改为 C
- **影响范围**: 对比表维度 3 结论变化，撤退条件更新
- **对应 Decision**: Decision #<N> in decisions.md

这样任何人看到文件都能追溯"为什么改了"。