review-a-design

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Review a design — is it sound, not just complete

评审设计——它是否合理，而不只是完整

The platform

/open-knowledge

skill still governs every markdown operation here (reads via

exec

, writes via

write

edit

, links as plain relative markdown, MCP owns in-scope

.md

); this skill layers design-review craft on top of it.

Three reviews are not the same review, and only one is this skill's job.

Completeness review asks: is every section filled in? (Are Drawbacks and Alternatives non-empty?)
Correctness review asks: are the individual claims true? (Does the benchmark really say 40ms? Is that API deprecated?)
Soundness review asks: should this be built at all, and is this the design that follows from the stated goals and constraints?

You are doing the third. A proposal can be complete and factually correct and still be the wrong design — solving a symptom, chosen before its goals, engaging only strawman alternatives. Completeness and correctness are cheap to check and someone else's pass. Say this to the user up front if there's any ambiguity about what kind of review they want, then do soundness.

You produce findings, not edits. The author decides what to change. Never rewrite the artifact under review unless explicitly asked.

平台的

/open-knowledge

skill 仍管辖此处所有 markdown 操作（通过

exec

读取，通过

write

edit

写入，链接采用普通相对 markdown，MCP 负责范围内的

.md

）；本 skill 在其基础上叠加设计评审方法。

三种评审不是同一种评审，而且只有一种属于本 skill 的职责范围。

**完整性评审（Completeness review）**问的是：每个章节都填写了吗？（Drawbacks 和 Alternatives 是否非空？）
**正确性评审（Correctness review）**问的是：单项声明是否属实？（benchmark 真的说是 40ms 吗？该 API 已弃用了吗？）
**合理性评审（Soundness review）**问的是：是否应该构建它，以及这是否是依据既定目标和约束推导出的设计？

你做的是第三种。proposal 可以既完整又事实正确，却仍然是错误设计——它解决的是症状，设计在目标确定之前就已选定，或者只与稻草人备选方案交锋。完整性和正确性验证起来成本低，应由其他 pass 负责。如果用户想进行的评审类型有任何歧义，应先向用户说明，然后执行合理性评审。

你产出的是评审发现，而不是修改。由作者决定要改什么。除非明确要求，否则绝不重写正在评审的材料。

Step 0: Identify the artifact and read it — and what it inherits

Step 0：识别评审对象并完整阅读——还要阅读它所承接的既有决策

HARD GATE: never review a design you have not read end to end, and never review it in isolation from the decisions it inherits. A review of the first half is worse than no review — it spends the author's trust on partial understanding.

Identify the type. It is one of:
- a proposal (
```
proposals/NNNN-name.md
```
  — Motivation / Design / Drawbacks / Alternatives / Unresolved questions),
- a spec (
```
specs/NNN-name/spec.md
```
  — Goals / Non-goals / Design / Migration / Test plan, with a
```
parent_proposal:
```
  ),
- a decision (
```
decisions/NNNN-title.md
```
  — Context / Decision / Consequences, with a
```
supersedes:
```
  chain), or
- an in-flight choice with no document yet (the user is deciding in conversation). This is a valid target — see Step 1.
Read it whole:
```
exec("cat proposals/0003-feature.md")
```
.
Read what it depends on. A design is only as sound as the ground it stands on:
- the parent proposal a spec links via
```
parent_proposal:
```
  , and any proposal a decision implements;
- the decisions it assumes —
```
exec("grep -rln <subsystem-keyword> decisions/")
```
  , then
```
cat
```
  the relevant ones. A design that contradicts an accepted ADR without noting it is a finding by itself.
- the prior postmortems in the same subsystem —
```
exec("ls -A postmortems/")
```
  and
```
search({ query: "<subsystem> failure" })
```
  . A postmortem names a failure mode; a design that reintroduces it is your highest-value catch.
- sibling proposals/decisions it supersedes or overlaps — follow the
```
supersedes:
```
  chain both directions.
If the design references source code, read the code with the host's native tools (
```
Read
```
,
```
Grep
```
) — source is outside the knowledge base. In-scope markdown stays on
```
exec
```
/
```
search
```
.

Do not proceed until you can name the goal, the constraints, and the prior decisions this design sits on top of.

**硬性门槛：绝不评审未完整阅读过的设计，也绝不能脱离它所继承的决策孤立地评审设计。**只评审前半部分比完全不评审更糟——它会消耗作者对你的信任，却只换来了片面的理解。

识别类型。它属于以下一种：
- 一份 proposal（
```
proposals/NNNN-name.md
```
  — Motivation / Design / Drawbacks / Alternatives / Unresolved questions），
- 一份 spec（
```
specs/NNN-name/spec.md
```
  — Goals / Non-goals / Design / Migration / Test plan，并带有
```
parent_proposal:
```
  ），
- 一份 decision（
```
decisions/NNNN-title.md
```
  — Context / Decision / Consequences，并带有
```
supersedes:
```
  链），或
- 一项尚未形成文档的进行中选择（用户正在对话中做决定）。这也是合法目标——参见 Step 1。
完整阅读：
```
exec("cat proposals/0003-feature.md")
```
。
阅读它所依赖的内容。设计是否合理，取决于它所立足的基础：
- spec 通过
```
parent_proposal:
```
  链接的父 proposal，以及 decision 所实现的任何 proposal；
- 设计所假设的 decisions——
```
exec("grep -rln <subsystem-keyword> decisions/")
```
  ，然后
```
cat
```
  相关文件。一个设计若与已接受的 ADR 相矛盾，却没有指出这一点，这本身就构成一项 finding；
- 同一子系统中的既往 postmortem——
```
exec("ls -A postmortems/")
```
  和
```
search({ query: "<subsystem> failure" })
```
  。postmortem 会指出一种失败模式；重新引入该失败模式的设计，就是价值最高的发现；
- 它所取代或重叠的同级 proposals/decisions——沿
```
supersedes:
```
  链双向追踪。
如果设计引用了源代码，应使用宿主环境的原生工具（
```
Read
```
、
```
Grep
```
）阅读代码——源代码位于知识库之外。范围内的 markdown 仍通过
```
exec
```
/
```
search
```
处理。

在你能够明确说出该设计所服务的目标、接受的约束以及所承接的既有决策之前，不要继续。

Step 1: Reconstruct the design's own argument — and show it back

Step 1：重构设计自身的论证——并将其呈现出来

Before you critique anything, state the design's argument in your own words: the goal it serves, the constraints it accepts, and why this design follows from them. Show it to the user before Step 2.

Why this gate exists:

If you can reconstruct it cleanly, the author gets a free confirmation that the intended reader understood it — often the most useful thing a review returns.
If you cannot state the goal, the constraints, and why this design follows from them, the reviewable object does not exist yet — and that IS the finding. Stop and report it: "I can't reconstruct why this design follows from its goals; here's where the chain breaks." Reviewing the surface of a design whose argument you can't state produces confident noise. Hand it back to the authoring skill to make the argument legible first.

For an in-flight choice with no document, this step is where you force the argument into words for the first time. Frequently the act of reconstruction resolves the question without a single lens.

在批评任何内容之前，先用自己的话陈述设计的论证：**它所服务的目标、它接受的约束，以及为什么这一设计能够由二者推导得出。**进入 Step 2 前，先向用户展示这一点。

设置此门槛的原因：

如果你能够清晰地重构论证，作者就会免费获得一次确认：预期的读者确实理解了设计——这往往是一次评审所能返回的最有价值的结果。
**如果你无法说明该设计为何从其目标推导而来，那么可评审的对象尚不存在——这本身就是 finding。**停止并报告：“我无法重构出该设计为何从其目标推导而来；论证链正是在这里断裂。”对一个连自身论证都无法陈述的设计进行表面评审，只会产出自信的噪声。应将其交回 authoring skill，先让论证变得可理解。

对于尚未形成文档的进行中选择，这个步骤就是首次迫使选择被表述成文字的地方。通常，仅重构论证本身就能解决问题，无需使用任何 lens。

Step 2: Run the soundness lenses

Step 2：应用合理性 lenses

Pass the design through each lens below. A lens is a named question plus the failure it catches — run the ones that bite for this artifact, skip the ones that plainly don't, and add any that earn their place. Do not mechanically fill all nine; a review that says the same shallow thing nine times teaches nothing.

Problem lens — Is the stated problem the real problem, or a symptom of one upstream? Whose problem is it, and what evidence says it hurts today (not hypothetically)? A design aimed at a symptom is unsound however elegant. Failure it catches: solving the wrong problem beautifully.
Goal-derivation lens — Does the design follow from the stated goals, or were the goals reverse-engineered to justify a design chosen first? Read the goals, then read the design cold: could you have predicted this design from these goals? If the design has a feature no goal demands, either the goal is unstated or the feature is scope. Failure it catches: solution-first rationalization.
Alternatives lens — Are the alternatives real, or strawmen? Take the strongest version of the rejected option — steelman it — and check whether the document engages with that, or with a weak caricature. An Alternatives section that dismisses each option in one dismissive sentence is a tell. Failure it catches: a foregone conclusion dressed as a comparison.
Constraint lens — Which constraints are hard, and which are inherited habit? Hard: physics, compliance, a one-way door already walked through, a contract with a downstream team. Soft: "we've always done it this way", a limit of the current tool, a deadline that could move. A design that treats a soft constraint as hard is under-imagined and probably larger than it needs to be. Failure it catches: unnecessary complexity justified by a fake wall.
Cost lens — What does this design foreclose, and what does it hand the team every week for the next three years? Name the ongoing obligation: the migration that can't be undone, the schema that now needs backfilling forever, the on-call surface. Blast radius is not just the launch; it's the maintenance tail. Failure it catches: a cheap-looking design with an expensive tail.
Reversibility lens — One-way door or two-way door? A two-way door (easily reverted) should be walked through, not committee'd — if the design is cheap to undo, over-reviewing it wastes everyone's time and the finding is "just ship it and learn." A one-way door (data migration, public API, external contract) deserves the scrutiny the two-way door didn't. Failure it catches: mis-spent rigor — heavy process on reversible choices, light process on irreversible ones.
Failure lens — What has to be true for this to work, and what happens at each assumption's boundary? List the load-bearing assumptions, then push each to its edge: what at 10x load, at zero network, at a hostile input, at the second concurrent writer? Cross-check the prior postmortems from Step 0: does this design reintroduce a named past failure? Failure it catches: a design sound in the happy path and broken at every boundary.
Simplicity lens — Is there a materially smaller design that satisfies the stated goals? Name it concretely — "drop the queue and call synchronously; the goals never mention throughput" — not "simplify it," which is not a finding. YAGNI is a soundness argument, not a style note: speculative generality is unsound because it pays cost for a goal no one stated. Failure it catches: a design solving problems it doesn't have yet.
Scope lens — Are the non-goals temporal and justified, or is load-bearing scope being smuggled out the back? A good non-goal says "not now, because X, and here's the seam that lets us add it later." A bad non-goal quietly excludes the hard half of the actual problem so the design looks tractable. Read every non-goal and ask whether the design still solves the real problem without it. Failure it catches: a tractable design for a shrunken problem.

使用以下各个 lens 检查设计。每个 lens 都是一个具名问题，以及它所能捕捉的失败。对本评审对象真正有影响的选择使用它们，跳过明显不适用的项，也可以补充确有价值的 lens。不要机械地走完全部九项；九次重复同一个浅层结论的评审毫无价值。

问题 lens（Problem lens）——*所陈述的问题是真问题，还是某个上游问题的症状？*这是谁的问题？有什么证据表明它今天正在造成伤害（而非仅仅是一种假设）？瞄准症状的设计无论多么精巧都不合理。它能捕捉的失败：把错误问题解决得很漂亮。
目标推导 lens（Goal-derivation lens）——*设计是否由既定目标推导而来，还是先选定设计，再反向编造目标来证明其合理性？*先读目标，再冷读设计：能否仅根据这些目标预测出这个设计？如果某项 feature 没有任何目标要求，那么要么目标尚未陈述，要么该 feature 属于范围蔓延。它能捕捉的失败：先有方案、后补理由的合理化。
备选方案 lens（Alternatives lens）——*备选方案是真实存在的，还是稻草人？*采用被否决方案的最强版本——为其 steelman——然后检查文档是在认真应对这个版本，还是只应对一个被刻意削弱的 caricature。如果 Alternatives 章节只用一句轻蔑的话就否定每个选项，这本身就是警示信号。它能捕捉的失败：把既定结论包装成比较。
约束 lens（Constraint lens）——*哪些约束是硬约束，哪些只是沿袭下来的习惯？*硬约束包括：物理规律、合规要求、已经走过且无法回头的单向门，以及与下游团队签订的契约。软约束包括：“我们一直这么做”、当前工具的限制，以及可以调整的截止日期。把软约束当作硬约束的设计，其想象空间不足，而且很可能远比实际所需更复杂。它能捕捉的失败：用一道根本不存在的墙为不必要的复杂度辩护。
成本 lens（Cost lens）——*这个设计封死了什么，又会在未来三年里每周给团队留下什么？*明确指出持续性负担：无法撤销的迁移、从此永远需要回填的 schema，或新增的 on-call 负担。影响范围不只包括上线阶段，还包括长期维护尾部。它能捕捉的失败：看似便宜的设计，却拖着昂贵的维护尾巴。
可逆性 lens（Reversibility lens）——*这是单向门还是双向门？*双向门（容易回退）应该直接走过去，而不是交给委员会审议——如果设计很容易撤销，过度评审只会浪费所有人的时间，此时 finding 应当是“直接发布，在实践中学习”。单向门（数据迁移、公开 API、外部契约）则值得投入另一类审查。它能捕捉的失败： rigor 用错地方——对可逆选择施加过重流程，对不可逆选择审查不足。
失败 lens（Failure lens）——*要让这个设计奏效，必须有哪些条件成立？每个假设到达边界时会发生什么？*列出所有承重假设，然后逐一推到边界：10 倍负载时如何？完全断网时如何？面对恶意输入时如何？出现第二个并发写入者时如何？**交叉核对 Step 0 中的既往 postmortem：这个设计是否重新引入了某种已知失败？**它能捕捉的失败：在 happy path 中合理，却在每个边界处都会失效的设计。
简洁性 lens（Simplicity lens）——*是否存在一个实质上更小、却仍能满足既定目标的设计？*具体说出它——“去掉队列，改成同步调用；目标从未提到吞吐量”——而不要只说“简化它”，因为那不是 finding。YAGNI 是一项合理性论证，而不只是风格备注：推测性泛化之所以不合理，是因为它为无人陈述的目标付出了成本。它能捕捉的失败：解决团队尚未遇到的问题。
范围 lens（Scope lens）——*非目标是基于时间划定且有合理依据，还是有承重范围被悄悄排除在外？*好的非目标会说明“现在不做，因为 X，并且这里预留了以后可扩展的接缝”。坏的非目标会悄悄排除真实问题中困难的一半，让设计看起来 tractable。逐条阅读每个非目标，并询问：没有它，设计是否仍能解决真实问题？它能捕捉的失败：为缩水后的问题设计出一个看似 tractable 的方案。

Step 3: Write findings

Step 3：撰写 findings

Each finding has four parts, and a finding missing the second is an opinion — drop it:

Claim — one sentence. What is unsound.
Evidence — quote the passage or link it:
```
the Design section says "[quoted text]"
```
or
```
[the Migration plan](./specs/012-sync/spec.md)
```
assumes X. A finding with no evidence pointer is an opinion; delete it. This is the single discipline that separates a review the author acts on from one they resent.
Severity — one of:
- blocking — the design should not proceed as written; a load-bearing assumption is wrong, or it reintroduces a known failure, or it solves the wrong problem.
- substantive — the design can proceed, but this materially weakens it and deserves an answer before acceptance.
- minor — worth noting, safe to defer or wave off.
Resolution — a concrete alternative or the question that would settle it. "This is worse" is not actionable; "consider a two-way-door version that does X, which drops the migration" or "what happens when two agents write the same doc — does the design address that?" is.

Rank by severity, not by reading order. Lead with the blocking findings; the author reads the top of your review and stops when they've got the gist. Burying the one blocking finding under six minor ones wastes it.

每条 finding 由四部分组成，缺少第二部分的 finding 只是意见——应将其删除：

Claim（主张）——用一句话说明设计中有何不合理之处。
Evidence（证据）——引用相关段落或给出链接：
```
Design 部分称“[引用文本]”
```
，或
```
[迁移计划](./specs/012-sync/spec.md)
```
假定 X。**没有证据指向的 finding 只是意见；应删除。**这是区分“作者愿意采取行动的评审”和“作者会反感的评审”的唯一纪律。
Severity（严重程度）——取以下值之一：
- blocking——设计不应按当前形式继续；某个承重假设有误，或重新引入了已知失败，或解决了错误的问题。
- substantive——设计可以继续，但存在实质削弱，采纳前应给出回应。
- minor——值得指出，但可以安全推迟或忽略。
Resolution（解决方案）——给出一个具体替代方案，或一个能够定论的问题。“这样更差”不可执行；“考虑一个采用双向门、去掉 migration 的版本”或“当两个 agent 写入同一份 doc 时会发生什么——设计是否处理了这种情况？”则可以。

**按严重程度排序，而不是按阅读顺序排序。**先列出 blocking findings；作者读到评审开头就会停下并抓住要点。把唯一的 blocking finding 埋在六条 minor findings 下面，只会浪费它。

Step 4: Calibrate — adversarially re-read your own findings

Step 4：校准——以对抗性方式重读自己的 findings

Before you deliver, turn the lenses on yourself. Reviews that flag everything teach the author to ignore reviews — the moment your review has one indefensible finding, the author discounts all of them.

Re-read each finding as the author would and try to kill it. If you can't defend the evidence, cut it.
State confidence per finding and what would change your mind: "blocking, high confidence — unless the load numbers in the parent proposal are wrong, in which case this drops to minor." A finding you can't attach a falsifier to is probably a preference, not a finding.
Collapse duplicates. Three findings that are the same root cause are one finding with three symptoms.
If after calibration you have zero blocking and zero substantive findings, say so plainly — "this is sound; here are two minor notes" is a complete and valuable review. Do not manufacture severity to look thorough.

交付前，把这些 lens 用在自己身上。事无巨细都标记问题的评审会教会作者忽略评审——只要出现一条站不住脚的 finding，作者就会把其余全部打折。

像作者一样重新阅读每条 finding，并尝试将其驳倒。如果无法为证据辩护，就删除它。
说明每条 finding 的置信度以及什么会改变你的判断：“blocking，高置信度——除非父 proposal 中的负载数字有误，否则会降为 minor。”无法附上可证伪条件的 finding 大概率只是偏好，而不是 finding。
合并重复项。根因相同的三条 findings 应合并为一条根因 finding，附带三个症状。
如果校准后没有 blocking 或 substantive findings，就直说——“这个设计是合理的；这里有两条 minor 备注”本身就是完整且有价值的评审。不要为了显得严谨而人为制造严重程度。

Step 5: Deliver

Step 5：交付

In conversation by default. Most reviews are a message: the reconstructed argument (Step 1), the ranked findings (Step 3), the calibration notes (Step 4).

Persist as a document ONLY when the user asks, or the review is substantial enough to be cited later (a blocking review of a proposal heading to accept/reject). Then:

Write it beside the artifact it reviews:

write({ document: { path: "proposals/0003-feature-review.md" } })

Link it from the artifact's Unresolved questions (proposal) or Open questions (spec) section via
```
edit
```
— a plain markdown link
```
[design review](./0003-feature-review.md)
```
, never backticked, never an HTML anchor.
Mark it advisory in its own frontmatter/opening line: this is input to the author, not a verdict. The author owns the artifact and decides what lands.

Never edit the design under review to "apply" a finding. You emit findings; the authoring skill applies them.

**默认在对话中交付。**大多数评审只是一条消息：重构后的论证（Step 1）、排序后的 findings（Step 3），以及校准说明（Step 4）。

仅当用户提出要求，或评审内容足够重大、以后需要引用时，才持久化为文档（例如，针对即将接受或拒绝的 proposal 所做的 blocking review）。然后：

将其写在被评审材料旁边：

write({ document: { path: "proposals/0003-feature-review.md" } })

。

通过
```
edit
```
从评审对象的 Unresolved questions（proposal）或 Open questions（spec）章节链接到它——使用普通 markdown 链接
```
[design review](./0003-feature-review.md)
```
，绝不要加反引号，也不要使用 HTML anchor。
在它自己的 frontmatter/开篇行中标记为 advisory：这是给作者的输入，不是裁决。评审对象归作者所有，由作者决定哪些内容落地。

绝不编辑正在评审的设计来“应用”某条 finding。你只产出 findings；由 authoring skill 应用这些修改。

Step 6: Hand off

Step 6：交接

Route blocking and substantive findings back to whoever owns the fix:

Findings on a proposal →
```
/frame-a-proposal
```
(the argument, alternatives, or motivation needs rework).
Findings on a spec →
```
/write-a-spec
```
(goals, non-goals, migration, or test plan needs rework).
A finding that has resolved into a made choice ("we discussed it; we're going with the synchronous version") →
```
/record-a-decision
```
, so the choice and its rationale land in
```
decisions/
```
with a
```
supersedes:
```
link if it overturns a prior ADR.
A finding that a past failure is being reintroduced → point the author at the specific
```
postmortems/YYYY-MM-DD-name.md
```
so the design engages with it explicitly.

Name the skill and the reason in your handoff so the author knows exactly where to go.

将 blocking 和 substantive findings 路由给负责修复的人：

针对 proposal 的 findings →
```
/frame-a-proposal
```
（论证、备选方案或动机需要重构）。
针对 spec 的 findings →
```
/write-a-spec
```
（目标、非目标、迁移或测试计划需要重构）。
已转化为既定选择的 finding（“我们已经讨论过，决定采用同步版本”）→
```
/record-a-decision
```
，将该选择及其理由记录到
```
decisions/
```
；如果它推翻了此前的 ADR，还要添加
```
supersedes:
```
链接。
重新引入既往失败的 finding → 指向具体的
```
postmortems/YYYY-MM-DD-name.md
```
，让设计明确回应它。

交接时注明 skill 名称和原因，让作者确切知道应该去哪里。

Non-goals

Not a completeness checklist. "Section X is empty" is only a finding if the emptiness makes the design unsound (no Alternatives means no evidence the option space was explored — that's the finding, not the empty heading).
Not a fact-check. Whether an individual claim is true is a correctness pass — a different job. You assume the claims and test whether the design that rests on them is sound. Flag a claim only when it's load-bearing AND you have specific reason to doubt it; otherwise route the fact-check separately.
Not a code review. Reviewing a diff for bugs, style, or implementation quality is out of scope. This skill reviews the design, not its code.
Not a rewrite. Never edit the artifact under review without being asked. You produce findings; the author changes the design.
Never the final verdict. The review is advice to the author, who owns the decision. A review that reads as a ruling — "rejected" — overreaches; a review that reads as "here's what would make this stronger, and here's what I'd block on and why" is doing its job.

不是完整性检查清单。“章节 X 是空的”只有在这种缺失导致设计不合理时才构成 finding（没有 Alternatives 意味着没有证据表明已探索 option space——这才是 finding，而不是空标题本身）。
**不是事实核查。**单项声明是否属实属于正确性评审——是另一项工作。你应假定这些声明成立，并检验依赖它们的设计是否合理。只有当某项声明具有承重作用，而且你有具体理由怀疑它时，才应标记该声明；否则将事实核查单独路由出去。
**不是代码评审。**评审 diff 中的 bug、style 或实现质量不在范围内。本 skill 评审设计，不评审代码。
**不是重写。**除非明确要求，否则绝不编辑正在评审的材料。你只产出 findings；由作者修改设计。
**绝不是最终裁决。**评审只是给作者的建议，最终决策权归作者。读起来像“已拒绝”的评审会越权；读起来像“以下内容能让设计更强，以及以下事项会构成阻断及原因”的评审，才是在正确履行职责。