--- 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 修改 / ← 项目维度 -/ ← 一次 review 会话 README.md ← 会话概览（自动生成/更新） decisions.md ← 决策日志（跨 Phase 累积） p1-position.md ← Phase 1 产出 p2-deconstruct.md ← Phase 2 产出 p3-deepdive/ ← Phase 3 产出（每个模块一个文件） module-a-.md module-b-.md p4-integrate.md ← Phase 4 产出 p5-converge/ ← Phase 5 产出 coding-plan.md ← 最终编码 Plan p6-verify.md ← Phase 6 验证报告 ``` ### 会话初始化 Preamble **每个 Phase 的 skill 开头都必须执行以下步骤：** ```bash # 读取配置 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//-/` 3. **如果是继续之前的 review**，列出最近的会话让用户选择 **会话目录一旦确定，后续所有 Phase 的产出都写入同一个会话目录。** ### README.md 自动更新 每个 Phase 完成后，更新会话目录下的 `README.md`： ```markdown # : Created: ## 进度 - [x] Phase 1: 定位 — <一句话总结> - [x] Phase 2: 解构 — - [ ] 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： ```markdown ## Decision #: <标题> - **Phase**: - **Date**: - **Module**: <模块名，如适用> - **Decision**: <做出的决定> - **Alternatives considered**: <被否决的方案> - **Rationale**: <为什么选这个> - **Decided by**: <决策人> - **Reference**: <业界参考链接，如有> - **Revisable**: <在什么条件下应该推翻这个决策> ``` **什么算"关键决策"：** 有 2+ 个合理方案、选了其中一个的情况。如果只有唯一合理方案，不需要记。 ## 迭代追踪（Revision Tracking） **当 P4 的结论倒逼 P3 修改方案时，不要直接覆盖原文件。** 在文件末尾追加修订记录： ```markdown --- ## Revision Log ### Rev 1 — - **触发原因**: P4 接口 review 发现 <问题> - **修改内容**: 推荐方案从 A 改为 C - **影响范围**: 对比表维度 3 结论变化，撤退条件更新 - **对应 Decision**: Decision # in decisions.md ``` 这样任何人看到文件都能追溯"为什么改了"。