design-review

design-review

对一个改动方案 / diff做 CLAUDE.md 强制的五维变更审计，产出每一维的判定（covered / gap / N-A-带理由），由非实施 agent 执行（apc/05 §2 S6 · apc/12 design-review 行；与 S5 code-review 同精神——实施者不自审自的设计）。

什么时候用：一个 design doc / migration / ADD COLUMN / 新 endpoint / UI 重做进评审门时，需要独立核对它有没有把五维都想全。这是设计期的漏，比 phase 末期补漏便宜 10×（CLAUDE.md 五维审计）。

评审独立性（第一铁律，P2-17）

评审由非实施 agent 执行——设计者不自审自的方案，与 no-self-approval 同精神。若你就是这份设计的作者 → 停手，让另一个 agent 审。

五维（缺一维 = 未闭合；N/A 也要显式写理由）

照 CLAUDE.md「Five-Dimension Change Audit」逐维答。任一维标"未考虑"/"待后续评估"不能进实施；N/A 也要显式写原因。

#	维度	必答问题（摘 CLAUDE.md）	证据手段
1	前端 UI/UX 渲染交互	用户在哪儿感知？哪些组件/hook/路径改？破坏交互肌肉记忆吗？刷新/跨设备？错误态如何 surface？	rg 组件/路由
2	服务端 data-model & 数据流	哪些 Prisma model / SQL table 改？migration 编号？读/写/缓存路径？同事务保证？跨实例 fan-out？	rg schema；ls src/im/sql | sort | tail 看下一个编号；双 Prisma（SQLite + MySQL）都改了吗
3	Endpoint spec	新增/改/弃用哪些 HTTP/WS/SSE？req/resp schema？认证级别？错误码？兼容策略？SDK 类型同步？	rg 路由/handler
4	Daemon runtime / SDK & local-cache-first	daemon SDK 要适配吗？本地 SQLite/FS/asset-cache 变化？离线 fallback？daemon↔cloud 版本协商？多语言 SDK 同步？	rg runtime/；想 local-first：cloud-only 的东西 daemon 学得到吗
5	Built-in skill / agent-role	影响 SKILL.md / AGENTS.md / SOUL.md / operatingPrinciples 吗？要新 built-in skill？role template backfill？agent 端 prompt 更新？	rg built-in-skills/ · role template

Procedure

1. 独立性自证（若挂 task）— 你不是设计作者

2. 逐维审，每维产一条判定

对每一维给一行判定，形状：

{ dimension: 1..5,
  verdict: covered | gap | n/a,
  reason: "<covered: 方案怎么覆盖的 + 残留问题 / gap: 漏了什么、会怎么坏 / n/a: 为什么这维不适用>" }

• gap 是承重判据：方案没提的维度，标 gap 并说清"这个洞会怎么坏"（如：cloud-only 的 cap，daemon 本地 LLM 路径学不到 → 离线不 enforce）。别因为方案没写就默默跳过当它 covered——静默跳过正是五维审计要抓的头号反 pattern（单维过度聚焦）。
• n/a 必须带理由：一维确实不适用（纯计费门不碰 agent 能力 → 第 5 维 N/A），显式写理由。不许留空、不许"待评估"。
• covered 不虚报：方案真覆盖的维度，标 covered、只列真实残留问题（错误码待补、跨设备回显待确认）。不要把正常设计说成 blocker——假阳会淹没真信号（照 S5 code-review "干净 diff 不虚报"）。

3. 汇总 + 点出被静默跳过的维度

产出：

• 五维判定表（每维 covered/gap/n-a + reason）。
• 承重发现：被方案静默跳过的维度（那个 enforcement/兼容/数据主权的洞）。
• openQuestions[]：拿不准的（不是 gap）。

输出契约（机器判据按这个复验，别自由发挥格式）

本 skill 的验收判据不是「报告里出现了 daemon / prisma 这些词」——旧判据就是六条这样的 match，一句 npm run prisma:generate 就能让"数据模型维已答"变绿。现在判据找的是每一维自己那一行，并把该行的引用读回磁盘复核（structured-criteria.ts 的 dimension-coverage）。

五维逐行作答（每维独占一行 + 固定 key，行首先给 verdict，再给理由，最后给证据）：

- [1] frontend-uiux: covered — <覆盖点 + 残留问题> | <path:line>
- [2] server-data-model: covered — <…> | <path:line>
- [3] endpoint-spec: covered — <…> | <path:line>
- [4] daemon-runtime-sdk: gap — <洞是什么、会怎么坏> | <daemon/runtime 侧真要改的 path:line>
- [5] skill-agent-role: gap — <…> | <path:line>    或    N/A — <理由 ≥20 字符>

判据强制三条：

1. 每维的行必须以 verdict 开头：covered / gap / N/A（中文 已覆盖 / 缺口 / 不适用 同义）。
2. covered / gap 的行必须带至少一条能在磁盘上复核的 path:line（文件存在、行号在范围内、该行非空）——rg -n 出来的行号，别猜。这就是"对码"：说方案漏了 daemon 层，就得指出 daemon 层真正要改的那一行。
3. N/A 的行必须带理由（去空白后 ≥20 字符）；只写 N/A 判红。

引用写法：必须 repo-root-relative（src/im/api/routes.ts:314，不要简写成 im/api/routes.ts:314，也不要绝对路径）；rg -c 出的 path:12 是命中计数不是行号，要写就写 count=12。

承重维度的 verdict 是被钉死的：sample task 里 daemon-runtime-sdk 必须是 gap。把它橡皮图章成 covered、或者把 "gap" 写在正文别处而不在那一行上，都判红——这正是五维审计要抓的头号反 pattern（静默跳过）。

产出（副作用 oracle，报告里必须给）

1. 五维全答：五个维度逐一有判定，无一维留空（N/A 也带理由）。
2. gap 被 surface：方案静默跳过的维度标成 gap / missing / not-addressed，说清怎么坏——不是橡皮图章全绿。
3. covered 不虚报：真覆盖的维度不编造 blocker。

不许：把方案没提的维度默默当 covered（静默跳过）；一维留空或写"待评估"就交（未闭合）；把正常设计说成 blocker 制造假阳；自审自的设计。

诚实边界

• LLM 设计评审是非确定性的：本 skill 不保证抓出所有设计缺陷，也不保证零漏报/零虚报。它保证的是"五维逐维走一遍 + 每维判定可核验（covered/gap/n-a 带理由）+ gap 说清怎么坏 + 不自审"。深层的跨维耦合缺陷可能漏——靠多轮评审 + 真实施后 test-runner 兜，不靠单次审打包票。
• 需要读代码核对的维度（"这个字段真有消费者吗"/"下一个 migration 编号"），依赖仓库可 rg/ls；只读方案文本时该维标注"未对码，基于方案陈述"。
• 本 skill 只产判定，不改设计——修由设计者按判定回改，再进下一轮审。

调用回执（APC 平台方运营纪律 · 自动注入，勿手改）

执行本 skill 的第一步，先落一条调用回执：

cloud skill ack design-review --task "$PRISMER_TASK_ID"

按退出码分流（这条命令的退出码是承重信息，禁止用 || 兜底、; true、 set +e 或重定向把它抹掉）：

exit	含义	你要做的
0	回执已落库（im_task_logs.action='skill_ack'）	继续执行本 skill
3	无 task 上下文——本次运行没有 task，产不出回执	继续执行本 skill；但本次运行没有回执，任何报告里都不得声称已 ack
4	你不是该 task 的 assignee，服务端拒绝	停下并上报：回执只能由执行该 task 的 agent 产生
1	其它失败（网络 / 服务端）	重试一次；仍失败则继续执行，并在结果里显式标注「回执缺失」

回执只证明本 skill 被调度，不证明执行正确——效果证明由本 skill 自己的 acceptanceCriteria 副作用断言承担（apc/04 §2 层 1 诚实标注）。