<SUBAGENT-STOP> If you were dispatched as a subagent to execute a specific task, skip this skill. </SUBAGENT-STOP>

<SUBAGENT-STOP> 如果你作为子代理被派去执行特定任务，请跳过此技能。 </SUBAGENT-STOP>

Instruction Priority

指令优先级

User's explicit instructions (CLAUDE.md, AGENTS.md, direct requests) — highest priority
OpenSpec artifacts (proposal.md, specs/, design.md, tasks.md) — the authoritative spec baseline
This skill's review process — validate artifacts before code
Default system prompt — lowest priority

If the user says "skip the review, just write code," follow the user's instructions. The user is in control.

用户明确指令（CLAUDE.md、AGENTS.md、直接请求）——最高优先级
OpenSpec工件（proposal.md、specs/、design.md、tasks.md）——权威规范基准
本技能的评审流程——编码前验证工件
默认系统提示词——最低优先级

如果用户说“跳过评审，直接写代码”，请遵循用户指令。用户拥有最终控制权。

SDD Review Specs

SDD规范评审

Overview

概述

AI-generated specs are initial drafts, not final contracts. They reflect what the AI understood — not necessarily what you intended. Reviewing specs is the most critical human judgment gate in spec-driven development.

Core principle: Every AI-generated spec artifact must be reviewed by a human before any code is written.

Announce at start: "I'm using the sdd-review-specs skill to review the OpenSpec artifacts."

Violating the letter of this review process is violating the spirit of spec-driven development.

AI生成的规范是初始草稿，而非最终约定。它们反映AI的理解——不一定是你的真实意图。评审规范是规范驱动开发中最关键的人工判断关卡。

核心原则： 所有AI生成的规范工件必须在编写任何代码前经过人工评审。

开始时声明： "我正在使用sdd-review-specs技能评审OpenSpec工件。"

违反此评审流程的字面要求，就是违反规范驱动开发的精神。

The Iron Law

铁律

NO CODE WITHOUT REVIEWED SPECIFICATIONS

If the 4 artifacts haven't been reviewed, you cannot proceed to implementation.

NO CODE WITHOUT REVIEWED SPECIFICATIONS

如果4个工件未经过评审，你不能进入实现阶段。

When to Review

评审时机

ALWAYS review after
/opsx:propose
generates artifacts. Never skip review because:

AI misinterprets scope boundaries
AI generates "happy path" specs with insufficient error coverage
AI makes technology choices incompatible with existing architecture
AI omits edge cases that a human would catch immediately

Review is NOT required for:

Tier 0 changes: one-line fixes, typos, log lines, comments (no artifacts to review)

在/opsx:propose生成工件后必须进行评审。 绝不能跳过评审，因为：

AI可能误解范围边界
AI生成的“理想路径”规范缺乏足够的错误覆盖
AI做出的技术选择可能与现有架构不兼容
AI会遗漏人类能立即发现的边缘情况

无需评审的场景：

0级变更：单行修复、拼写错误、日志行、注释（无工件需要评审）

Tier-Based Review Depth

基于层级的评审深度

Not every change needs the same review depth. Classify by scope:

Tier	Applies To	Review Scope	Time
Tier 0 — Skip	Typo fixes, log lines, comments, one-line changes	No artifacts exist. Verify with build/lint directly.	0 min
Tier 1 — Light	Single-field additions, simple validation changes, config tweaks	Review `proposal.md` scope + `tasks.md` executability. Skim `design.md` .	5-10 min
Tier 2 — Full	New features, cross-package refactors, architecture changes, API additions	Full review of all 4 artifacts with complete checklist.	15-30 min

If unsure, default to Tier 2. Over-reviewing is cheaper than missing a critical issue.

并非所有变更都需要相同的评审深度。按范围分类：

层级	适用场景	评审范围	耗时
0级 — 跳过	拼写修复、日志行、注释、单行变更	无工件存在。直接通过构建/代码检查验证。	0分钟
1级 — 轻量	单字段新增、简单验证变更、配置调整	评审 `proposal.md` 范围 + `tasks.md` 可执行性。略读 `design.md` 。	5-10分钟
2级 — 完整	新功能、跨包重构、架构变更、API新增	使用完整检查表全面评审所有4个工件。	15-30分钟

若不确定，默认采用2级评审。 过度评审比遗漏关键问题成本更低。

The Gate Function

门控流程

dot

digraph review_gate {
    rankdir=TB;
    "4 artifacts generated\nby /opsx:propose" [shape=doublecircle];
    "Identify tier\n(Tier 0, 1, or 2?)" [shape=diamond];
    "Skip review\n(no artifacts)" [shape=box style=filled fillcolor="#ccffcc"];
    "Tier 1 Light Review\n(5-10 min)" [shape=box style=filled fillcolor="#ffffcc"];
    "Tier 2 Full Review\n(15-30 min)" [shape=box style=filled fillcolor="#ffcccc"];
    "Read artifacts in order\nproposal → specs → design → tasks" [shape=box];
    "Check against\nchecklist" [shape=box];
    "Issues found?" [shape=diamond];
    "Communicate issues\nwith suggested fixes" [shape=box style=filled fillcolor="#ffcccc"];
    "Re-check affected\nartifacts" [shape=box];
    "Write review.md\nto change directory" [shape=box];
    "Declare review passed\n→ writing-plans" [shape=doublecircle];

    "4 artifacts generated\nby /opsx:propose" -> "Identify tier\n(Tier 0, 1, or 2?)";
    "Identify tier\n(Tier 0, 1, or 2?)" -> "Skip review\n(no artifacts)" [label="Tier 0"];
    "Identify tier\n(Tier 0, 1, or 2?)" -> "Tier 1 Light Review\n(5-10 min)" [label="Tier 1"];
    "Identify tier\n(Tier 0, 1, or 2?)" -> "Tier 2 Full Review\n(15-30 min)" [label="Tier 2"];
    "Tier 1 Light Review\n(5-10 min)" -> "Read artifacts in order\nproposal → specs → design → tasks";
    "Tier 2 Full Review\n(15-30 min)" -> "Read artifacts in order\nproposal → specs → design → tasks";
    "Read artifacts in order\nproposal → specs → design → tasks" -> "Check against\nchecklist";
    "Check against\nchecklist" -> "Issues found?";
    "Issues found?" -> "Communicate issues\nwith suggested fixes" [label="yes"];
    "Issues found?" -> "Write review.md\nto change directory" [label="no"];
    "Communicate issues\nwith suggested fixes" -> "Re-check affected\nartifacts";
    "Re-check affected\nartifacts" -> "Check against\nchecklist";
    "Write review.md\nto change directory" -> "Declare review passed\n→ writing-plans";
}

BEFORE proceeding to any implementation:

1. IDENTIFY tier — Tier 0, 1, or 2?
2. READ each artifact in order: proposal → specs/ → design → tasks
3. CHECK against the checklist for your tier (below)
4. FEEDBACK — communicate every issue found, with suggested fix
5. ITERATE — after AI fixes, re-check affected artifacts
6. ONLY THEN — declare review passed
7. PRODUCE review evidence — write review result to openspec/changes/<name>/review.md
   (minimum: tier chosen, checklist results, issues found/resolved, pass/fail declaration)
8. ROUTE — to superpowers:writing-plans

dot

digraph review_gate {
    rankdir=TB;
    "4 artifacts generated\nby /opsx:propose" [shape=doublecircle];
    "Identify tier\n(Tier 0, 1, or 2?)" [shape=diamond];
    "Skip review\n(no artifacts)" [shape=box style=filled fillcolor="#ccffcc"];
    "Tier 1 Light Review\n(5-10 min)" [shape=box style=filled fillcolor="#ffffcc"];
    "Tier 2 Full Review\n(15-30 min)" [shape=box style=filled fillcolor="#ffcccc"];
    "Read artifacts in order\nproposal → specs → design → tasks" [shape=box];
    "Check against\nchecklist" [shape=box];
    "Issues found?" [shape=diamond];
    "Communicate issues\nwith suggested fixes" [shape=box style=filled fillcolor="#ffcccc"];
    "Re-check affected\nartifacts" [shape=box];
    "Write review.md\nto change directory" [shape=box];
    "Declare review passed\n→ writing-plans" [shape=doublecircle];

    "4 artifacts generated\nby /opsx:propose" -> "Identify tier\n(Tier 0, 1, or 2?)";
    "Identify tier\n(Tier 0, 1, or 2?)" -> "Skip review\n(no artifacts)" [label="Tier 0"];
    "Identify tier\n(Tier 0, 1, or 2?)" -> "Tier 1 Light Review\n(5-10 min)" [label="Tier 1"];
    "Identify tier\n(Tier 0, 1, or 2?)" -> "Tier 2 Full Review\n(15-30 min)" [label="Tier 2"];
    "Tier 1 Light Review\n(5-10 min)" -> "Read artifacts in order\nproposal → specs → design → tasks";
    "Tier 2 Full Review\n(15-30 min)" -> "Read artifacts in order\nproposal → specs → design → tasks";
    "Read artifacts in order\nproposal → specs → design → tasks" -> "Check against\nchecklist";
    "Check against\nchecklist" -> "Issues found?";
    "Issues found?" -> "Communicate issues\nwith suggested fixes" [label="yes"];
    "Issues found?" -> "Write review.md\nto change directory" [label="no"];
    "Communicate issues\nwith suggested fixes" -> "Re-check affected\nartifacts";
    "Re-check affected\nartifacts" -> "Check against\nchecklist";
    "Write review.md\nto change directory" -> "Declare review passed\n→ writing-plans";
}

在进入任何实现阶段之前：

1. 确定层级——0级、1级还是2级？
2. 按顺序阅读每个工件：proposal → specs/ → design → tasks
3. 根据你的层级检查表进行检查（如下）
4. 反馈——传达发现的所有问题，并给出建议修复方案
5. 迭代——AI修复后，重新检查受影响的工件
6. 只有此时——宣布评审通过
7. 生成评审证据——将评审结果写入openspec/changes/<name>/review.md
   （最低要求：所选层级、检查表结果、发现/解决的问题、通过/失败声明）
8. 流转——调用superpowers:writing-plans

Tier 2 Full Review Checklist

二级完整评审检查表

Create a task for each artifact. Complete in order.

为每个工件创建一个任务，按顺序完成。

1. proposal.md — Scope & Motivation

1. proposal.md — 范围与动机

Motivation clear: Can a new team member understand WHY this change exists by reading the first 3 sentences?
Scope explicit: Is every in-scope item concretely named (not "and related features")?
Out of scope explicit: Are excluded items listed with reasons ("deferred to future change" vs "not applicable")?
No scope creep signals: No phrases like "and similar improvements" or "as needed"
Boundary contract: If someone later asks "can we add X to this change?", can you answer by pointing to in/out scope?

动机明确： 新团队成员阅读前3句话后，能否理解此变更的存在原因？
范围明确： 每个范围内的项目是否都有具体名称（而非“及相关功能”）？
排除范围明确： 是否列出了排除项及原因（“推迟到后续变更” vs “不适用”）？
无范围蔓延迹象： 没有“及类似改进”或“按需”等表述
边界约定： 如果有人后来问“我们能否在此次变更中添加X？”，你能否通过指向包含/排除范围来回答？

2. specs/ — Behavioral Completeness

2. specs/ — 行为完整性

Happy paths covered: Every in-scope item in proposal.md maps to ≥1 behavioral requirement in specs/
Error paths covered: For every happy path, are there corresponding error/edge case requirements?
Input validation: Are invalid inputs, boundary values, and null/empty states addressed?
State transitions: If the feature involves state changes, are all transitions defined?
No vague language: No "should handle errors appropriately" without specifying HOW
Interface signatures: If the spec defines functions/APIs, are signatures concrete (types, parameters, return values)?
Consistency with proposal.md: Does every spec requirement fall within proposal.md's scope?

覆盖理想路径： proposal.md中的每个范围内项目都对应specs/中至少1项行为要求
覆盖错误路径： 每个理想路径是否都有对应的错误/边缘情况要求？
输入验证： 是否处理了无效输入、边界值和空/空状态？
状态转换： 如果功能涉及状态变化，是否定义了所有转换？
无模糊表述： 没有“应适当处理错误”而不说明具体方式的表述
接口签名： 如果规范定义了函数/API，签名是否具体（类型、参数、返回值）？
与proposal.md一致： 每个规范要求是否都在proposal.md的范围内？

3. design.md — Technical Soundness

3. design.md — 技术合理性

Approach justified: Does it explain WHY this approach over alternatives?
Alternatives documented: Are rejected alternatives listed with rejection reasons?
Dependency check: Do new dependencies conflict with existing ones?
Existing patterns respected: Does the design follow established project conventions?
Integration points: Are touch points with existing modules explicitly named?
Risks identified: Are there risk items and mitigation strategies?
Concurrency/performance: If relevant, are goroutine/thread safety, memory, and latency considered?

方案有依据： 是否解释了为何选择此方案而非其他替代方案？
记录替代方案： 是否列出了被否决的替代方案及否决原因？
依赖检查： 新依赖是否与现有依赖冲突？
遵循现有模式： 设计是否符合既定项目惯例？
集成点： 是否明确列出了与现有模块的接触点？
风险识别： 是否有风险项和缓解策略？
并发/性能： 若相关，是否考虑了协程/线程安全、内存和延迟？

4. tasks.md — Executability

4. tasks.md — 可执行性

Complete coverage: Does every in-scope item from proposal.md map to ≥1 checkbox?
Test tasks included: Does every implementation task have a corresponding test task?
No vague tasks: No "handle edge cases" or "add appropriate error handling" — each task is concrete
Correct ordering: Do dependent tasks come after their dependencies?
Independently executable: Can a developer (or AI) pick up any single task and complete it without reading others?
Verifiable per task: Is there a clear "done" signal for each checkbox (test passes, file exists, etc.)?

完整覆盖： proposal.md中的每个范围内项目是否都对应至少1个复选框？
包含测试任务： 每个实现任务是否都有对应的测试任务？
无模糊任务： 没有“处理边缘情况”或“添加适当的错误处理”——每个任务都具体明确
顺序正确： 依赖任务是否在其依赖项之后？
可独立执行： 开发者（或AI）能否拿起任何单个任务并完成，而无需阅读其他任务？
每个任务可验证： 每个复选框是否有明确的“完成”信号（测试通过、文件存在等）？

Tier 1 Light Review Checklist

一级轻量评审检查表

proposal.md: Scope boundaries clear? In/out scope reasonable?
tasks.md: Each task concrete and executable? Test tasks paired with implementation tasks?
design.md (skim): Any obviously wrong technology choices? Any conflict with existing dependencies?
specs/ (skim): Any obvious missing error paths?

proposal.md： 范围边界是否清晰？包含/排除范围是否合理？
tasks.md： 每个任务是否具体且可执行？测试任务是否与实现任务配对？
design.md（略读）： 是否有明显错误的技术选择？是否与现有依赖冲突？
specs/（略读）： 是否有明显缺失的错误路径？

Red Flags — STOP and Revise

危险信号——立即停止并修订

These patterns in AI-generated artifacts mean the spec is NOT ready:

AI生成的工件中出现以下模式意味着规范尚未就绪：

proposal.md Red Flags

proposal.md危险信号

"and related features" / "as needed" / "etc." — scope creep by design
In-scope list has 10+ items — change is too large, split it
No out-of-scope section — AI avoided saying "no"

“及相关功能” / “按需” / “等等”——设计上存在范围蔓延
包含范围列表有10个以上项目——变更过大，应拆分
无排除范围部分——AI回避说“不”

specs/ Red Flags

specs/危险信号

All happy paths, zero error paths — AI only described the ideal case
"should work correctly" / "should handle errors" — too vague to verify
No edge cases (empty input, null, boundary values, concurrency) — incomplete
Requirements that can't be tested — "the system should be fast"

全是理想路径，没有错误路径——AI只描述了理想情况
“应正常工作” / “应处理错误”——过于模糊无法验证
无边缘情况（空输入、null、边界值、并发）——不完整
无法测试的需求——“系统应快速”

design.md Red Flags

design.md危险信号

"Use [technology]" without explaining WHY — missing decision record
No alternatives section — AI didn't consider other approaches
"Similar to [existing module]" without specifics — lazy design
Introduces a new dependency without noting it — architectural drift
Ignores existing project conventions — AI didn't read project.md/CLAUDE.md

“使用[技术]”但未解释原因——缺失决策记录
无替代方案部分——AI未考虑其他方法
“类似于[现有模块]”但无具体细节——设计敷衍
引入新依赖但未注明——架构漂移
忽略现有项目惯例——AI未阅读project.md/CLAUDE.md

tasks.md Red Flags

tasks.md危险信号

Tasks with "and" in the name — should be split
No test tasks — TDD impossible without them
"Refactor as needed" / "Add error handling" — placeholder tasks
Tasks ordered alphabetically rather than by dependency — wrong order

Any of these red flags means: the artifact is not ready. Give specific feedback and request revision.

名称中带有“和”的任务——应拆分
无测试任务——没有测试任务就无法进行测试驱动开发
“按需重构” / “添加错误处理”——占位任务
任务按字母顺序而非依赖顺序排列——顺序错误

出现任何这些危险信号意味着：工件尚未就绪。给出具体反馈并要求修订。

Common Rationalizations

常见合理化借口

Excuse	Reality
"The AI usually gets this right"	AI makes systematic mistakes. Review catches them.
"I'll catch issues during implementation"	Finding issues during coding costs 10x more to fix.
"The spec looks reasonable at a glance"	Skimming is not reviewing. Use the checklist.
"This is too small to need review"	Small changes have the most unexamined assumptions.
"I trust the AI's design decisions"	Trust but verify. The AI doesn't know your unwritten conventions.
"Review takes too long"	Rework from unreviewed specs takes longer.
"I already reviewed it during brainstorming"	Brainstorming explores. Propose formalizes. They're different artifacts.
"The tests will catch spec issues"	Tests verify implementation, not design quality. Wrong design + passing tests = wrong product.
"A targeted partial review is honest pragmatism"	Partial review is partial compliance. The tier exists for a reason — if it's Tier 2 by classification, Tier 1 review is insufficient.
"Full review when tired is performative"	Fatigue degrades thoroughness, but skipping review entirely guarantees zero thoroughness. Defer the review — don't rationalize a skim.

All of these mean: do the review. Follow the checklist.

借口	真相
“AI通常能做好这件事”	AI会犯系统性错误。评审能发现这些错误。
“我会在实现过程中发现问题”	在编码过程中发现问题的修复成本是评审阶段的10倍。
“规范乍一看合理”	略读不是评审。请使用检查表。
“这个变更太小，不需要评审”	小变更有最多未经审视的假设。
“我信任AI的设计决策”	信任但要验证。AI不知道你的不成文惯例。
“评审太费时间”	未评审规范导致的返工耗时更长。
“我在头脑风暴时已经评审过了”	头脑风暴是探索。Propose是正式化。它们是不同的工件。
“测试会发现规范问题”	测试验证实现，而非设计质量。错误的设计+通过的测试=错误的产品。
“有针对性的部分评审是务实的做法”	部分评审是部分合规。层级的存在是有原因的——如果分类为2级，1级评审是不够的。
“疲劳时的完整评审是形式主义”	疲劳会降低彻底性，但完全跳过评审意味着彻底性为零。推迟评审——不要为略读找借口。

所有这些借口都指向：进行评审。遵循检查表。

Skill Types

技能类型

sdd-review-specs is a RIGID skill. The gate function is non-negotiable for Tier 2. Follow the checklist exactly. Don't adapt away the sequence.

Within the review process:

Tier classification — Use judgment. When unsure, default to Tier 2.
Checklist execution — Rigid. Every item must be checked.
Issue communication — Flexible. Adapt feedback style to the context.

sdd-review-specs是一项严格的技能。 对于2级评审，门控流程不可协商。严格遵循检查表。不要调整流程顺序。

在评审流程内：

层级分类——使用判断。若不确定，默认采用2级。
检查表执行——严格。每个项目都必须检查。
问题沟通——灵活。根据上下文调整反馈风格。

Common Failures

常见误区

Claim	Requires	Not Sufficient
"Specs reviewed"	Every checklist item checked, issues documented, review.md written to change directory	"Read through it", "looks fine"
"Scope is clear"	In/out scope sections are explicit and complete	"I know what they mean"
"Design is solid"	Alternatives documented, decisions justified, risks noted	"The approach makes sense"
"Tasks are executable"	Each task concrete, independently verifiable, correctly ordered	"The list looks complete"
"Ready for implementation"	All red flags resolved, tier-appropriate checklist passed, review.md present	"Should be good enough"
"Review done — I checked tasks.md boxes"	sdd-review-specs gate function invoked with tier classification and checklist results	Checking off implementation tasks in tasks.md is progress tracking, not spec review

声明	必备条件	不充分条件
“规范已评审”	检查了每个检查表项目，记录了问题，评审结果已写入变更目录的review.md	“读过了”、“看起来没问题”
“范围清晰”	包含/排除范围部分明确且完整	“我知道他们的意思”
“设计可靠”	记录了替代方案，决策有依据，注明了风险	“方案合理”
“任务可执行”	每个任务具体、可独立验证、顺序正确	“列表看起来完整”
“准备好实现”	所有危险信号已解决，通过了对应层级的检查表，存在review.md	“应该足够好”
“评审完成——我勾选了tasks.md的框”	调用了sdd-review-specs门控流程，包含层级分类和检查表结果	勾选tasks.md中的实现任务是进度跟踪，不是规范评审

After Review Passes

评审通过后

Review passed → invoke superpowers:writing-plans to refine task granularity.
                Save the implementation plan to openspec/changes/<name>/plan.md.

REQUIRED SUB-SKILL: Use superpowers:writing-plans to convert the reviewed tasks.md into 2-5 minute bite-sized tasks. Save output to

openspec/changes/<name>/plan.md

— all artifacts for this change live in one directory. The reviewed artifacts are now the authoritative spec baseline — writing-plans works from them.

评审通过 → 调用superpowers:writing-plans细化任务粒度。
            将实现计划保存到openspec/changes/<name>/plan.md。

必备子技能： 使用superpowers:writing-plans将已评审的tasks.md转换为2-5分钟即可完成的小任务。将输出保存到

openspec/changes/<name>/plan.md

——此变更的所有工件都存放在一个目录中。已评审的工件现在是权威规范基准——writing-plans基于它们工作。

User Instructions

用户说明

Review is the human judgment gate, not a blocker. AI generates fast. Humans decide correctly. If you want to skip review or downgrade from Tier 2 to Tier 1, say so explicitly. The skill provides the framework, you provide the judgment.

评审是人工判断关卡，而非障碍。AI生成速度快。人类决策更准确。如果你想跳过评审或从2级降级到1级，请明确说明。本技能提供框架，你提供判断。

The Bottom Line

底线

No code before reviewed specs.

Read each artifact. Check against the checklist. Flag every issue. Only when all artifacts pass review does implementation begin.

This is non-negotiable.

未评审规范，不写代码。

阅读每个工件。对照检查表检查。标记每个问题。只有当所有工件通过评审后，才能开始实现。

这一点不可协商。

sdd-review-specs

Original

Translation