gstack /plan-devex-review 详解：以证据先行的开发者体验计划评审技能

gstack /plan-devex-review 详解：以证据先行的开发者体验计划评审技能

【免费下载链接】gstackUse Garry Tan's exact Claude Code setup: 23 opinionated tools that serve as CEO, Designer, Eng Manager, Release Manager, Doc Engineer, and QA项目地址: https://gitcode.com/GitHub_Trending/gs/gstack

本篇围绕 gstack 仓库中的 plan-devex-review/SKILL.md 展开，拆解/plan-devex-review这个"计划阶段的开发者体验（DX）评审"技能的完整工作流：从产品类型自动识别、Step 0 证据链（开发者人设拷问、共情叙事、竞品 TTHW 基准、魔性时刻设计）到 8 条 DX 评审通道、DX 记分卡与跨模型"Outside Voice"挑战，再到退出 Plan Mode 前的强制门禁。读完本文，你能理解该技能"先调查、后打分"的设计哲学，掌握其评分标尺与三种评审模式（DX EXPANSION / DX POLISH / DX TRIAGE）的取舍，并能在自己的 API/CLI/SDK 计划评审中复用它的方法论。

1. 技能定位：评审的是"计划"，不是代码

/plan-devex-review是 gstack 提供的一组计划评审技能之一（同族还有/plan-ceo-review、/plan-eng-review、/plan-design-review）。它的 SKILL frontmatter 声明了关键元信息：name: plan-devex-review、interactive: true、version: 2.0.0、benefits-from: [office-hours]，允许的工具为 Read、Edit、Grep、Glob、Bash、AskUserQuestion、WebSearch。触发词包括 "DX review"、"developer experience audit"、"devex review"、"API design review"，以及口语音频别称 "dx review"、"onboarding review" 等。

技能对自身的定位非常明确（原文原话）：

"Your job is not to score a plan. Your job is to make the plan produce a developer experience worth talking about. Scores are the output, not the process." "Do NOT make any code changes. Do NOT start implementation."

也就是说，它的输出是一份更好的计划，而不是一份关于计划的文档；评审过程中禁止做任何代码改动、禁止开始实现。同时它对适用对象设了门槛：DX 评审针对的是 API、CLI、SDK、库、平台、文档这类"面向开发者的产品"，且"DX is UX for developers……The bar is higher because you are a chef cooking for chefs"（用户是职业开发者，标准更高）。

2. 适用性门禁：产品类型自动检测

进入评审前，技能会读取计划内容并推断开发者产品类型：

• 提及 API endpoints、REST、GraphQL、gRPC、webhooks →API/Service
• 提及 CLI 命令、flags、参数、terminal →CLI Tool
• 提及 npm install、import、library、package →Library/SDK
• 提及 deploy、hosting、infrastructure →Platform
• 提及 docs、guides、tutorials、examples →Documentation
• 提及 SKILL.md、skill template、Claude Code、MCP →Claude Code Skill

如果以上都不匹配，技能会直接退出并建议改用/plan-eng-review或/plan-design-review。检测命中后，它会向用户陈述分类请求确认（"I'm reading this as a CLI Tool plan. Correct?"），产品类型会直接影响 Step 0A 提供的人设选项，以及后续是否运行"Claude Code Skill DX Checklist"附录。

3. DX 知识框架：原则、特征、标尺与基准

技能的推荐必须可追溯到 8 条 DX 第一性原理（"Every recommendation traces back to one of these"）：

1. Zero friction at T0— 前 5 分钟决定一切。一次点击开始，不读文档就能 hello world，不需要信用卡、不需要销售电话。
2. Incremental steps— 不允许开发者先理解整个系统才能从局部获得价值。要缓坡，不要悬崖。
3. Learn by doing— Playground、sandbox、可复制粘贴的真实代码；参考文档是必要的但永远不充分。
4. Decide for me, let me override— 有主见的默认值是特性，逃生门（escape hatch）是必需品。
5. Fight uncertainty— 开发者需要知道：下一步做什么、刚才是否成功、失败怎么修。每条错误 = 问题 + 原因 + 修复。
6. Show code in context— "Hello world 是谎言"。要展示真实鉴权、真实错误处理、真实部署。
7. Speed is a feature— 响应时间、构建时间、完成任务所需代码行数、要学习的概念数量，都是速度。
8. Create magical moments— Stripe 的即时 API 响应、Vercel 的 push 即部署，找到属于你产品的"魔性时刻"并让它成为开发者体验到的第一件事。

配套的"七大 DX 特征"给出了每个维度的含义与黄金标杆：

此外还有 10 条"认知模式"（Chef-for-chefs、前 5 分钟偏执、错误信息共情、逃生门意识、旅程完整性、上下文切换成本、升级恐惧、SDK 完整性、Pit of Success、渐进式披露），要求评审者"内化而不是罗列"。

评分采用 0-10 校准表：9-10是 Stripe/Vercel 级别的开发者盛赞；7-8可用且无挫败感；5-6有摩擦但可容忍；3-4开发者抱怨、采用率受损；1-2首次尝试即弃用；0完全没考虑过该维度。核心方法是"gap method"：对每个分数，先解释对这个产品而言 10 分长什么样，再朝 10 分修复。

衡量首体验的核心指标是TTHW（Time to Hello World）：

评审进行到每条 pass 时，技能要求按 pass 加载dx-hall-of-fame.md 中对应章节（"Read ONLY the section for the current pass. Do NOT load the entire file."），以控制上下文体积。该文件按 pass 组织了 Stripe、Vercel、Clerk、Supabase、Firebase、Twilio 等黄金案例与反模式（如"先验证邮箱再给任何价值"、"沙箱前要求信用卡"、"多路径自选冒险造成决策疲劳"）。错误消息部分定义了三档质量标杆：Tier 1 Elm 式会话式编译器（第一人称、精确位置、建议修复）、Tier 2 Rust 式注释源码（错误码链接教程、主/次标签、help 段展示精确编辑）、Tier 3 Stripe API 式结构化 JSON（type/code/message/param/doc_url五字段零歧义），公式为"发生了什么 + 为什么 + 怎么修 + 去哪学 + 实际触发值"。

4. 前置系统审计与 PREREQUISITE 建议

评审前技能先做"PRE-REVIEW SYSTEM AUDIT"：运行git log --oneline -15、git diff $(git merge-base HEAD main …) --stat收集上下文，然后阅读计划文件、CLAUDE.md（项目约定）、README.md（现有上手体验）、docs/ 目录结构、package.json（开发者将安装的东西）、CHANGELOG.md。同时做"DX 工件扫描"：grep README 中的 "Getting Started"/"Quick Start"/"Installation"、CLI 帮助文本（--help、usage:）、错误消息模式（throw new Error、console.error）、已有的 examples/ 或 samples/ 目录，并检查设计文档（~/.gstack/projects/$SLUG/*-$BRANCH-design-*.md与仓库内DESIGN.md/docs/designs/*.md，后者在至少同样新鲜时优先，对应 issue #703 的双写策略）。

若未找到设计文档，技能会提供前置建议：先运行/office-hours生成结构化问题陈述、前提挑战与备选方案探索（约 10 分钟），再回到评审。用户选择执行时，技能会内联读取 office-hours/SKILL.md 并跳过其中已由父技能处理的章节（Preamble、AskUserQuestion Format、Telemetry 等），完成后重新执行设计文档检测。frontmatter 中的benefits-from: [office-hours]正是这种"技能组合"（skill composition）关系的声明。

5. Step 0：评分前的证据链（0A-0G）

这是整个技能的核心原则："gather evidence and force decisions BEFORE scoring, not during scoring"。Steps 0A-0G 构建证据基础，使后续 pass 1-8 用证据而非感觉打分。在上下文压力下，其优先级为：Step 0 > Developer Persona > Empathy Narrative > Competitive Benchmark > Magical Moment Design > TTHW Assessment > Error quality > Getting started > API/CLI ergonomics > 其他；"Never skip Step 0, the persona interrogation, or the empathy narrative."

0A 开发者人设拷问（Persona Interrogation）。先收集证据（README 的 "who is this for"、package.json 描述/关键词、设计文档、docs/ 的受众信号），再按产品类型提供 3 个人设原型 + "让我自己描述"。人设示例覆盖：为 MVP 而生的 YC 创始人（30 分钟集成容忍度、不读文档、照抄 README）、C 轮平台工程师（重视安全/SLA/CI 集成）、前端开发者（TS 类型、bundle 体积）、后端 API 集成者（cURL 示例、鉴权流、限流文档）、GitHub 上的开源贡献者（git clone && make test、CONTRIBUTING.md）、学习编程的学生、DevOps 工程师（Terraform/Docker、非交互模式）。用户确认后产出人设卡：

TARGET DEVELOPER PERSONA ======================== Who: [描述] Context: [何时/为何遇到这个工具] Tolerance: [放弃前的分钟/步骤数] Expects: [尝试之前假设已存在的]

此处是STOP点——不回答不继续，因为人设塑造整个评审。

0B 共情叙事（Empathy Narrative）。以人设第一人称写 150-250 词叙述，走真实的 README/docs 上手路径，引用真实文件与内容（"I open the README. The first heading is [actual heading]……"），然后展示给用户请求校准（A 准确 / B 部分错误 / C 完全跑偏）。这份叙事会成为计划文件的必备输出节"Developer Perspective"，让实现者"感受到开发者的感受"。

0C 竞品 DX 基准。用 WebSearch 跑三个检索式（"[类别] getting started developer experience {年份}"、"[最近竞品] developer onboarding time"、"[类别] SDK CLI developer experience best practices {年份}"），WebSearch 不可用时回退到参考基准（Stripe 30 秒 TTHW、Vercel 2 分钟、Firebase 3 分钟、Docker 5 分钟）。产出竞品基准表（工具 / TTHW / 值得借鉴的 DX 选择 / 来源），并让用户在 Champion（<2min）/ Competitive（2-5min）/ 维持现状 / 自述约束中选定 TTHW 落点——该层级成为 Pass 1 的基准。

0D 魔性时刻设计（Magical Moment Design）。先加载 Hall of Fame 的 "## Pass 1" 章节作为黄金案例，再为产品类型识别最可能的"魔性时刻"，并提供四种交付载体的权衡（均带人效/CC 双刻度工时标注）：A) 交互式 playground/sandbox（零安装、需构建托管环境，human ~1 周 / CC ~2h，例 Stripe API explorer）；B) 复制粘贴的 demo 命令（一条命令产出魔性输出，human ~2 天 / CC ~30min，例npx create-next-app）；C) 视频/GIF 演示（被动观看、零摩擦，human ~1 天 / CC ~1h）；D) 用开发者自己数据引导的教程（参与最深、到魔最慢）。选择结果会被后续评分 pass 持续追踪。

0E 模式选择。三档深度，且"Once selected, commit fully. Do not silently drift"：

• DX EXPANSION— DX 可以成为竞争优势，提出超出计划覆盖面的进取型 DX 改进，每一项扩容都通过独立问题 opt-in。
• DX POLISH— 计划范围正确，把每个触点做到无懈可击：错误消息、文档、CLI 帮助、上手指南；不加范围，极致严谨（多数评审的默认推荐）。
• DX TRIAGE— 只盯会阻断采用的关键 DX 缺口，快速、外科手术式，适合急着发版的计划。

上下文默认：新开发者产品 → EXPANSION；现有产品增强 → POLISH；修复/紧急发版 → TRIAGE。

0F 开发者旅程追踪。对 Discover、Install、Hello World、Real Usage、Debug、Upgrade 六个阶段，逐一追踪真实路径（读了哪个文件、执行了哪条命令、看到什么输出，引用具体文件与行号），用证据定位摩擦点（不是"安装可能困难"，而是"README 第 3 步要求 Docker 在运行，但没有任何检查或提示，没有 Docker 的 [人设] 会看到 [具体报错]"），然后每个摩擦点单独发一个 AskUserQuestion（严禁合并），选项形如 A) 在计划中修复（具体修法）/ B) 替代方案 / C) 显著文档化该要求 / D) 可接受摩擦-跳过。各模式覆盖不同：TRIAGE 只追 Install 与 Hello World；POLISH 全阶段；EXPANSION 全阶段且每阶段追问"怎样让它成为同类最佳？"。最终产出更新后的旅程地图表格。

0G 首次开发者角色扮演。用人设 + 旅程追踪写一份带时间戳的"confusion report"（T+0:00 做什么、T+0:30 困惑点……T+3:00 最终放弃/成功/求助），必须基于审计到的真实文档与代码，最后让用户选择处理哪些困惑点（全部修复 / 自选 / 只修关键项 / "这不现实——我们的开发者已经知道 X"）。此处同样是 STOP 点。

6. 三种模式的行为差异

review-sections.md 末尾的 Mode Quick Reference 给出了三模式对照：

| DX EXPANSION | DX POLISH | DX TRIAGE Scope | Push UP (opt-in) | Maintain | Critical only Posture | Enthusiastic | Rigorous | Surgical Competitive | Full benchmark | Full benchmark | Skip Magical | Full design | Verify exists | Skip Journey | All stages + | All stages | Install + Hello | best-in-class | | World only Passes | All 8, expanded | All 8, standard | Pass 1 + 3 only Outside voice| Recommended | Recommended | Skip

0-10 评分法对每节要求"Evidence recall"：引用 Step 0 中与该维度相关的具体发现。关键规则原文："Every rating MUST reference evidence from Step 0. Not 'Getting Started: 4/10' but 'Getting Started: 4/10 because [persona from 0A] hits [friction point from 0F] at step 3, and competitor [name from 0C] achieves this in [time].'" 评分后的修复循环为：证据回溯 → 打分 → 说明 10 分是什么 → 加载 Hall of Fame 对应段 → 编辑计划补全 → 重打分 → 有真实 DX 抉择就 AskUserQuestion → 再修，直到 10 分或用户说"够好，继续"。模式差异：EXPANSION 在修到 10 分后继续追问"怎样让它 best-in-class、让人设赞叹"并以独立 opt-in 问题呈现扩容项；POLISH 修掉每个缺口、不抄近路、每个问题落到具体文件/行；TRIAGE 只标记会阻断采用的缺口（分数低于 5），跳过 nice-to-have（5-7 分）。

7. 八条评审通道与反跳段规则

Step 0 完成后，技能要求完整读取 sections/review-sections.md（这是"决策树骨架 + 按需章节"设计：SKILL.md 里的 Section index 与 sections/manifest.json 只是被动注册表，"do not work from memory"）。该文件开头有两条硬性规则：

• Anti-skip rule：任何计划类型都不允许浓缩、缩写或跳过 1-8 任一 pass；"This is a strategy doc so DX passes don't apply" 永远是错的；某 pass 确实零发现就写 "No issues found"，但必须评估过。
• Anti-shortcut clause：计划文件是交互评审的输出而非替代品。把所有发现一次性写进计划然后直接 ExitPlanMode，正是"2026 年 5 月 transcript bug"的失败形态——只要有任何非平凡发现，从发现到 ExitPlanMode 的路径必须经过 AskUserQuestion；全零发现才是唯一可绕过提问的路径。

八条 pass 及其评估要点：

1. Pass 1：Getting Started（Zero Friction）— 零到 hello world 能否 <5 分钟？评估安装（一条命令？无前置？）、首次运行是否产出可见有意义的输出、sandbox/playground、免费层（无信用卡/无销售电话）、quick start 是否可复制粘贴且展示真实输出、鉴权引导步骤数、0D 选定的魔性时刻载体是否真的进了计划、与 0C 目标层级的 TTHW 差距。FIX TO 10 的验收：写出理想上手序列，精确到命令、预期输出、每步时间预算，目标 3 步以内；并跑 "Stripe test"——[人设] 能否在一个终端会话内、不离终端，从"没听说过"走到"跑通了"。
2. Pass 2：API/CLI/SDK Design（Usable + Useful）— 命名不查文档能猜对吗？每个参数有合理默认吗？整个 API 面模式一致吗？是否 100% 覆盖（开发者会不会退化为裸 HTTP）？能否从 CLI/playground 自助探索？可靠性语义（延迟、重试、限流、幂等、离线行为）？渐进式披露？接口是否匹配人设的心智模型（"YC 创始人期望tool.do(thing)，平台工程师期望tool.configure(options).execute(thing)"）。好 API 测试：[人设] 看一个例子后能否正确使用。
3. Pass 3：Error Messages & Debugging（Fight Uncertainty）— 从计划或代码库中追踪 3 条具体错误路径，对照 Hall of Fame 的三档体系逐条评估"当前开发者看到什么 vs 应该看到什么"；另评权限/沙箱/安全模型的爆炸半径清晰度、debug 模式、堆栈是有用信息还是框架噪音。
4. Pass 4：Documentation & Learning（Findable + Learn by Doing）— 信息架构（<2 分钟找到所需？）、渐进式披露（新手见简单、专家找进阶）、代码示例是否可复制且真实上下文、交互元素（playground、"try it" 按钮）、文档版本与开发所用版本匹配、tutorial 与 reference 是否兼备。
5. Pass 5：Upgrade & Migration Path（Credible）— 向后兼容的破坏面、弃用警告是否提前且可执行（"use newMethod() instead"）、每个 breaking change 是否有分步迁移指南、是否有 codemod、版本策略（语义化版本？）。
6. Pass 6：Developer Environment & Tooling（Valuable + Accessible）— 编辑器集成（LSP、补全）、CI/CD（GitHub Actions/GitLab CI、非交互模式）、TypeScript 类型、测试支持（易 mock？）、本地开发（热重载、watch、快反馈）、跨平台（Mac/Linux/Windows、Docker、ARM/x86）、本地环境可复现性、可观测/可测试性（dry-run、verbose、sample apps、fixtures）。
7. Pass 7：Community & Ecosystem（Findable + Desirable）— 代码开源与否、许可是否宽松、社区渠道（哪里提问、是否有人答）、示例是否真实可跑、插件/扩展生态、贡献指南、定价透明度（无账单惊吓）。
8. Pass 8：DX Measurement & Feedback Loops— TTHW 是否被度量/埋点、旅程分析（开发者在哪流失）、反馈机制（bug 报告、NPS、反馈按钮）、定期 friction 审计、以及"boomerang readiness"——实施后/devex-review能否测量现实与计划的偏差。

附录Claude Code Skill DX Checklist（仅当产品类型含 "Claude Code skill" 时运行，不打分）：逐项检查 AskUserQuestion 设计、状态存储（全局~/.tool/vs 按项目$SLUG/vs 按会话，审计用 append-only JSONL）、渐进式同意（一次性提示 + marker 文件、不再重问、可逆）、自动升级（版本检查 + 缓存 + snooze 退避 + 迁移脚本）、技能组合（benefits-from 链、评审链、内联调用 + 章节跳过）、错误恢复、会话连续性（timeline 事件、压缩恢复、跨会话学习）、有界自治（破坏性动作强制升级、审计轨迹）。

8. 必备输出与 DX 记分卡

评审必须产出（"Required Outputs"）：开发者人设卡（置于计划 DX 节顶部）、共情叙事（含用户纠正）、竞品 DX 基准表（附评审后分数）、魔性时刻规格、旅程地图（含全部摩擦点处置）、首次开发者困惑报告（标注哪些已处理）、"NOT in scope"节（考虑过但明确推迟的改进及一行理由）、"What already exists"节（计划应复用的现有文档/示例/错误处理/DX 模式）、TODOS.md 更新（每条 DX 债单独发一个 AskUserQuestion，含 What/Why/Pros/Cons/Context/依赖六要素，选项 A) 入 TODOS.md B) 跳过 C) 现在就做）。

DX Scorecard汇总 8 个维度的分数、Prior 分数与趋势箭头，外加 TTHW、竞争排名（Champion/Competitive/Needs Work/Red Flag）、魔性时刻（designed/missing + 交付载体）、产品类型、模式与 Overall DX；下半部是"DX PRINCIPLE COVERAGE"（Zero Friction / Learn by Doing / Fight Uncertainty / Opinionated + Escape Hatches / Code in Context / Magical Moments 各记 covered/gap）。判读规则：全部 8+ → "DX plan is solid"；任一维度低于 6 → 标记为关键 DX 债并说明采用影响；TTHW > 10 分钟 → 阻断性问题。

紧随其后是DX Implementation Checklist（17 项）：TTHW 低于 0C 目标、安装一条命令、首次运行有意义输出、魔性时刻按 0D 载体交付、每条错误含"问题+原因+修复+文档链接"、命名可猜、每参数有默认值、文档示例可复制且真实可用、示例展示真实用例、升级路径有迁移指南、breaking change 有弃用警告 + codemod、含 TS 类型（如适用）、CI/CD 免特殊配置、免费层无信用卡、changelog 存在且维护、文档可搜索、社区渠道存在且有人值守。

评审收尾还会把发现综合成Implementation Tasks：扁平任务列表，每项必须派生自某个具体发现（"If a finding produced no actionable task, do not invent one"），标注 P1（阻断发版）/P2（同分支落地）/P3（后续 TODO）、双刻度工时（human / CC）、文件清单与验证方式；同时用jq -nc逐条写入~/.gstack/projects/$SLUG/tasks-devex-review-<ts>.jsonl工件（严禁手写 JSONL；零任务也要 touch 空文件，以便聚合器区分"跑了但无发现"与"没跑"）——这个 JSONL 供/autoplan跨阶段聚合。

9. Outside Voice：默认开启的跨模型二评

八条 pass 之后，技能自动（非 opt-in）运行独立第二意见："Two models agreeing on a plan is stronger signal than one model's thorough review." 只有用户显式执行gstack-config set codex_reviews disabled才关闭。预检（preflight）探测CODEX_MODE：disabled直接跳过（不降级到子代理）；under_codex（会话已在 Codex 宿主内，嵌套 codex 等于同模型自审且 token 成本倍增，见 #2519）跳过 codex 调用并打印一行说明（GSTACK_FORCE_CODEX_REVIEW=1可强制）；not_installed/not_authed/model_unusable回退到 Claude 子代理路径（子代理拥有全新上下文即真正的独立视角，同样设 5 分钟超时防挂起）；ready则运行：

TMPERR_PV=$(mktemp /tmp/codex-planreview-XXXXXXXX) _REPO_ROOT=$(git rev-parse --show-toplevel) || { echo "ERROR: not in a git repo" >&2; exit 1; } codex exec "<prompt>" -C "$_ROO_T" -s read-only -c 'model_reasoning_effort="high"' -c 'web_search="cached"' < /dev/null 2>"$TMPERR_PV"

（原文为-C "$_REPO_ROOT"，5 分钟超时，结束后cat读取 stderr，全文原样呈现于CODEX SAYS (plan review — outside voice):分隔块中，不得截断或摘要。）构造的 prompt 以文件系统边界指令开头（禁止读取~/.claude/、.claude/skills/等技能定义目录，避免浪费 Codex 的时间），然后要求"brutally honest technical reviewer"找出第一轮评审漏掉的：幸存的逻辑缺口与未声明假设、过度复杂（是否有更简单的根本方案）、被想当然的可行性风险、缺失依赖或顺序问题、战略错配（"is this the right thing to build at all?"）。计划内容超过 30KB 时截断并注明。

呈现后处理跨模型张力：凡二评与本轮发现相左之处，以CROSS-MODEL TENSION:块中立呈现双方并指出"我可能缺什么上下文"。这里有一条明确的User Sovereignty原则：绝不把二评建议自动并入计划，每个实质性张力点都走 AskUserQuestion（A 采纳二评 / B 维持现状 / C 先调查 / D 记入 TODOS.md），"Cross-model agreement is a strong signal but NOT permission to act"。用户选 B 则维持现状，不得再争。结果经gstack-review-log持久化（skill 记为codex-plan-review，STATUS=clean/issues_found，SOURCE=codex/claude）。

10. 收尾协议：门禁、日志、仪表盘与计划文件报告

Review Log（PLAN MODE EXCEPTION — ALWAYS RUN，只写~/.gstack/）：

~/.claude/skills/gstack/bin/gstack-review-log '{"skill":"plan-devex-review","timestamp":"TIMESTAMP","status":"STATUS","initial_score":N,"overall_score":N,"product_type":"PRODUCT_TYPE","tthw_current":"TTHW_CURRENT","tthw_target":"TTHW_TARGET","mode":"MODE","persona":"PERSONA","competitive_tier":"COMPETITIVE_TIER","unresolved":N,"commit":"COMMIT"}'

STATUS 为"分数 ≥8 且 0 未决"时clean，否则issues_open。

Review Readiness Dashboard通过gstack-review-read读取各评审技能最近 7 天内的日志，展示 Eng/CEO/Design/Adversarial/Outside Voice 五行的 Runs、Last Run、Status、Required，并给出 VERDICT：Eng Review 是唯二默认门槛（7 天内有 clean 条目即 CLEARED，skip_eng_review=true时显示 SKIPPED (global) 并 CLEARED）；CEO/Design/Codex 评审仅展示不阻断。陈旧性检测采用"内容优先"规则：diff 作用行的wtree字段与当前工作树哈希相等即视为 CURRENT（同一内容，无论 rebase/amend）；计划层评审则保持 7 天新鲜度逻辑，若条目带plan_sha256可与当前计划文件比对并提示"plan changed since review"。

Plan File Review Report把结构化报告写进计划文件本身，格式为## GSTACK REVIEW REPORT表格（CEO Review / Codex Review / Eng Review / Design Review / DX Review 五行的 Trigger、Why、Runs、Status、Findings；DX Review 行的 Findings 由评审日志字段生成："score: {initial}/10 → {overall}/10, TTHW: {current} → {target}"），表下附 CODEX/CROSS-MODEL（可省略）与必有 VERDICT 行。强制约定：报告最后一条非空白行必须是不加粗的NO UNRESOLVED DECISIONS或**UNRESOLVED DECISIONS:**块的最后一条 bullet——防止跨评审重复计数（本评审的未决项从上下文列，历史评审取各自最新新鲜行的unresolved求和，丢弃当前技能自身行）。写入必须"先删后追加"：报告必须且只能是计划文件的最后一个##节，原地替换是被明令禁止的历史 bug 路径。

EXIT PLAN MODE GATE（BLOCKING）在调用 ExitPlanMode 前强制执行 5 项自检：(1) 用 Read 工具重读计划文件；(2) 确认最后一个##标题正是## GSTACK REVIEW REPORT（正文中提到 "outside voice"、"codex findings" 之类的散文不算数）；(3) 报告含 Runs/Status/Findings 表与 VERDICT 行；(4) 报告最后一条非空白行是未决状态行，加粗哨兵、拖尾散文、缺失均判 FAIL；(5) 若本次调用有计划文件在场，确认gstack-review-log已调用且gstack-review-read至少运行一次。技能特别提醒一个自欺失败模式："feeling 'done' after writing review prose into the plan body. The body prose is not the report." 跳过门禁硬调 ExitPlanMode 被定性为契约违约。

Review Chaining收尾时用 AskUserQuestion 推荐下一步：A)/plan-eng-review（DX 问题常带架构影响，API 设计/错误处理/CLI 人体工学问题应由工程评审验证修复）；B)/plan-design-review（存在面向终端用户的 UI 时）；C) 实施完成后跑/devex-review（"boomerang"：计划说 TTHW 会是 [0C 目标]，现实是否兑现？）；D) 手动处理。

11. 源码级佐证：这套技能在 gstack 里如何被"工程化"

从源码结构看，该技能的很多承诺在 gstack 代码库中有对应的实现与测试：

• 按需章节机制。sections/manifest.json 声明自己是 "PASSIVE registry"——只有 id/file/title/trigger 文本，"The skeleton's decision-tree prose decides WHEN to read"。即 SKILL.md 是决策树骨架，review-sections.md仅在 Step 0 完成后按索引加载，这正是第 4 行注释（"AUTO-GENERATED from SKILL.md.tmpl — do not edit directly, Regenerate: bun run gen:skill-docs"）所对应的模板化生成流程。
• DX 框架被两个技能共享。scripts/resolvers/dx.ts 的generateDxFramework()把 8 条第一性原理、七特征表、10 条认知模式、0-10 评分表、TTHW 基准表与 Hall of Fame 指针生成到模板中，文件头注释写明它是 "Shared……for /plan-devex-review and /devex-review"，且"Hall of Fame examples are NOT included here……loaded on-demand per pass to avoid prompt bloat"——与 SKILL.md 中"每 pass 只读对应章节"的要求互相印证。
• Brain 缓存的按技能配置。scripts/brain-cache-spec.ts 中，plan-devex-review的 preflight 恰好加载product、developer-persona、recent-decisions、competitive-intel四份 digest（与 SKILL.md 的 "Brain Context (preflight)" 一节完全对应），并登记/plan-devex-review会失效 developer-persona 相关缓存、该技能写入 brain 的 take 权重为 0.6。
• 问题偏好注册表。scripts/question-registry.ts 为该技能注册了三个稳定 question_id：plan-devex-review-persona（clarification 类，two-way）、plan-devex-review-mode（routing 类，选项 expand/polish/triage，signal_key 为devex-care）、plan-devex-review-friction-fix（approval 类，选项 fix-now/defer/skip）。SKILL.md 要求把<gstack-qid:{question_id}>标记嵌入问题文本，使 PreToolUse 钩子能确定性识别并支持/plan-tune的 auto-decide（自动选推荐项并提示 "Change with /plan-tune"）。
• E2E 回归测试守护"必须提问"的契约。test/skill-e2e-plan-devex-finding-floor.test.ts（gate 级、真实 PTY）注入 test/fixtures/forcing-finding-seeds.ts 中的FORCING_FLOOR_DEVEX种子——一份"SDK quickstart docs"计划：8 步上手（手动装 bun、填 8 个环境变量、对本地 Postgres 跑迁移、发邮件注册 API key……），"No quickstart command, no hosted sandbox, no copy-pasteable curl example"。测试断言：种子中嵌了这么多明显 DX 问题后，agent 必须至少触发一次 AskUserQuestion（outcome必须为auq_observed），否则测试失败。这正是 anti-shortcut clause（发现必须经 AskUserQuestion 才能到 ExitPlanMode）在自动化层的落点。

12. 使用前提与运行说明

适用前提与限制：该技能是 Claude Code 宿主上的交互技能（frontmatterinteractive: true、allowed-tools含 AskUserQuestion），假设 gstack 已安装于~/.claude/skills/gstack/（preamble 中大量调用~/.claude/skills/gstack/bin/gstack-*系列本地二进制，如gstack-config、gstack-slug、gstack-review-log、gstack-learnings-search），并在 git 仓库内运行（Step 0 的平台/基线分支检测、review log 的 commit 字段都依赖 git）。preamble 会回显若干会话级开关——PROACTIVE（是否主动建议技能）、SKILL_PREFIX（是否用/gstack-*前缀命名）、REPO_MODE（solo/collaborative 决定"看到别人的问题是否要主动修"）、SESSION_KIND（interactive/headless/spawned，影响提问失败时的回退策略）、CHECKPOINT_MODE（continuous 时以WIP:前缀自动提交逻辑单元）、GSTACK_PLAN_MODE（plan 文件存在时置 active）等——这些与具体 DX 评审逻辑解耦，属于 gstack 全体技能共享的运行骨架。遥测默认off/本地写入~/.gstack/analytics/，远程上报为显式 opt-in；学习记录（gstack-learnings-log）与评审日志（gstack-review-log）全部落在本机~/.gstack/，不外传。

在 Plan Mode 下调用时，技能指令明确"skill takes precedence over generic plan mode behavior"：技能文件是可执行指令而非参考资料，从 Step 0 开始逐步执行；允许的操作为只读探查、写~/.gstack/、写计划文件（"Writing the plan file is the one edit allowed in plan mode"）以及标记 "PLAN MODE EXCEPTION — ALWAYS RUN" 的命令；ExitPlanMode 只能在技能工作流完成后（并通过 EXIT PLAN MODE GATE）调用。

13. 小结

/plan-devex-review的价值不在"给 DX 打分"，而在它把评审做成了证据先行的强制过程：先用人设卡与共情叙事锚定"为谁做"，用竞品 TTHW 基准锚定"做到什么程度"，用魔性时刻与旅程追踪锚定"在哪发力"，再以八条固定 pass + 反跳段/反抄近路规则保证覆盖，用记分卡与未决决策哨兵保证产出可审计，用跨模型二评 + 用户主权保证结论经过第二视角。配合实施后的/devex-review回旋镖验证，这套"计划评审 → 实现 → 实测复盘"闭环，是 gstack 将 DX 从主观感觉变成可追踪、可回归（见第 11 节的 e2e floor 测试）、可复利（learnings 与 brain 缓存）的工程实践。

【免费下载链接】gstackUse Garry Tan's exact Claude Code setup: 23 opinionated tools that serve as CEO, Designer, Eng Manager, Release Manager, Doc Engineer, and QA项目地址: https://gitcode.com/GitHub_Trending/gs/gstack