opsx-solve-workflow

OPSX 八阶段问题解决工作流

将 solve-workflow 的八阶段 PDCA 规范与 OpenSpec/OPSX 工件持久化相结合。目标是：不让 AI 跳过分析、提案、评审或验证，也不让关键结论只存在于聊天上下文中。

输出模板：各阶段的格式请参见 reference.md。

定位

将此技能用于值得持久化的工程变更：需求、根本原因、行为变更、技术权衡、任务清单和验证结果都应写入 openspec/changes/<change-name>/，完成后再通过归档合并到 openspec/specs/。

分工：

• OpenSpec：事实来源和归档系统——回答“是什么、为什么”。
• solve-workflow-style gates：阶段门控——回答“何时可以进入下一步”。

不取代普通的 solve-workflow：

• 快速修复、单文件轻量编辑，或无需长期追溯的任务——优先使用 solve-workflow。
• 涉及长期行为约定、团队评审、并发变更、需求审计或后续追溯的任务——使用此技能。

调用约定

• 触发词：opsx解决, OpenSpec解决, 规范化解决, 创建OpenSpec变更, 创建opsx变更, 用OpenSpec分析, 用OpenSpec修复, opsx自动解决, OpenSpec自动解决, opsx-solve, opsx-solve-workflow; ai-proxy 模式, AI 代理模式, 切换 ai-proxy
• 模式：overlay 触发词（「ai-proxy 模式」「AI 代理模式」「切换 ai-proxy」 / "ai-proxy mode" / "switch to ai-proxy"）根据 workflow-mode-lifecycle 请求 overlay（如果同时存在自动触发词，则以 overlay+freeze 为准）。否则，包含“自动”的触发词会进入自动模式；默认进入手动模式。
• 手动模式：阶段 1、2、3、4、5、7、8 的关键退出点必须等待用户确认。
• 自动模式：自动推进，直至验证；阶段 4 的评审循环最多进行 3 轮，然后暂停。

无人值守代理退出：当本次运行约定或任务卡记录了 Stage-exit policy: ai-proxy（自动载体；队列子项可以有，也可以没有）时，上述每个手动退出点都将根据 ai-proxy-discipline 成为代理检查点。精简冻结（口头触发 ≠ 占用）在该规范中说明。执行前审批点采用代理的有界预授权，而不是 design-approval-gate 的裸自动绕过。合并、不可逆操作和受保护分支的决策仍仅限人工处理（暂存并创建工单）。任何其他策略值或未设置策略 → 行为与当前一致。

停止点预测：如果本次运行以已冻结的约定开始（包含问题和冻结决策的队列子项，或已写入的独立精简冻结），则在分析前先输出预测表——列出每个手动退出点，并标明其由冻结决策覆盖，还是将形成新工单。如果在运行中途请求 overlay，则在精简冻结后输出剩余退出点的预测，然后继续当前阶段（不要从分析阶段重新开始）。 强依赖技能（frontmatter dependencies；启动时必须通过“前置技能检查”——如果缺少任何一项，则中止）：

• staged-review-flow（第 4 阶段审查编排；依赖 solution-review 和 code-design-review）
• hybrid-debug / runtime-evidence-debug / browser-debug-toolkit（通过 analysis-core 委派；第 2 阶段和第 7 阶段）
• analysis-core（第 2 阶段分析方法的唯一来源：临时变更门槛 / 默认以 runtime-evidence-debug 为入口的插桩调试 / 分析步骤骨架 / 分析门槛输出块 / 调试验证循环）
• context-budget-discipline（第 6/7 阶段入口：阶段边界重置评估、主动压缩阈值、任何重置前移交台账）
• node-version-discipline（第 7 阶段 Node 版本对齐）
• learn-and-improve（第 8 阶段回顾与知识沉淀）
• workflow-mode-lifecycle（自动 / 手动模式生命周期）
• clarifying-question-discipline（主动提问 + 优先调查的严格规范）
• known-issue-research（第 2 阶段研究路由 / 已知问题快速搜索 / 行业范围评估）
• competitive-research（分析期间用户可见的竞品行为；方法保留在该技能中）
• test-suite-ensure（第 6 阶段确保测试套件：有基础设施时补全并运行测试；没有时经用户确认后搭建脚手架）
• test-first-discipline（第 6 阶段：行为变更先编写失败测试；与 test-suite-ensure 不同）
• design-approval-gate（第 6 阶段前：未经批准不得进行生产实现；具名的自动 / 热修复例外）
• delivery-discipline（第 8 阶段：归档后可选提交 + 创建 / 更新 PR/MR；并非每次运行都会交付）
• feature-branch-closeout（第 8 阶段：归档后收尾菜单；合并委派给 merge-discipline）
• decision-fog-discipline（探索解决方案前：先厘清模糊点 / 创建决策工单）
• git-worktree-discipline（第 3 阶段前——首次写入产物之前：工作树门槛 + 可选隔离工作区）
• domain-language-discipline（澄清 / 分析：涉及领域术语时使用项目词汇表 / CONTEXT.md）
• merge-discipline（第 8 阶段合并规范——收尾选定合并后）
• opsx-workspace-gate（第 0 阶段 OpenSpec 工作区和原生技能门槛）
• figma-pixel-implement / figma-pixel-verify（忠实于 Figma 导出的实现 + 测量验证；必须已安装；当目标、卡片、问题或计划包含 figma.com 或 node-id=，或用户要求按像素还原时调用）

前置技能检查

启动时（第 0 阶段门槛通过后、第 1 阶段开始前），检查 frontmatter dependencies：扫描可用技能；如果缺少任何一项 → 打印结构化提示并立即中止（格式：solve-workflow/reference.md「前置技能检查 — 缺失通知」）。

不降级原则：缺少强依赖意味着中止——绝不回退到简化版审查或调试流程。

模式生命周期

自动模式的进入、持续和退出规则，用于防止用户不知情时模式持续生效、AI 仍在自动做出决策。核心规则（恢复为手动 / 显式重新进入 / 隐式继续不重新激活 / 批处理场景）由强依赖技能 workflow-mode-lifecycle 规定（前置检查已保证该技能可用）——此处不再重复。

OpenSpec 专项说明

• 第 8 阶段归档完成后，模式会自动恢复为手动。
• 如果用户决定开始新一轮 PDCA（返回第 3/4/5 阶段），默认使用手动模式。
• 归档中断（例如 openspec-archive-change 技能失败）也视为流程中断——恢复为手动模式。

---

阶段 0：环境检查与路径选择

此技能要求 OpenSpec 工作区已完全初始化；不提供降级路径。加载 opsx-workspace-gate，并运行其项目根目录定位、openspec/ 检查和精确的原生 OPSX 技能门禁；通过后，此工作流将继续执行自身的阶段门禁和下游编排。

通过门禁后的准备步骤

1. 决定使用现有变更还是创建新变更，并且只准备一个候选名称：
   • 如果用户指定了变更，优先使用该变更。
   • 否则，为新工作生成一个 kebab-case 候选名称，并在手动模式下与用户确认。
2. 准备创建方式，但在阶段 1 用户确认之前不要创建目录：通过 openspec-new-change 技能创建变更（读取其 SKILL.md，然后遵循其中的说明）。

路径选择

根据任务选择一条路径，并在继续之前声明：

路径	适用情况	要求
完整	全新功能、复杂模块、需求模糊	完整执行阶段 1-8
增量	对现有行为的变更、重构、一般错误修复	执行阶段 1-8，但提案/规格可以保持精简
精简	热修复、小型且确定性高的变更	保留提案、增量规格、任务、验证和归档——绝不跳过验证

如果执行过程中范围扩大，必须升级路径：精简 → 增量，增量 → 完整。在手动模式下，升级需要用户确认。

阶段与产物的对应关系

阶段	目标	OpenSpec 存放位置	代码写入
1. 明确问题	就问题达成一致，提取要素，解决未决问题	仅分析，不创建产物	禁止
2. 分析问题	确认问题是否存在，定位根因，评估影响	仅分析，不创建产物（结论在阶段 3 后写入 proposal.md）	禁止
3. 探索解决方案	提出 2-5 个解决方案并选定一个	通过 openspec-continue-change 写入 proposal.md（完整内容）+ specs/<capability>/spec.md（增量规格）	禁止
4. 评审解决方案	评审有效性、风险和可行性	通过 openspec-continue-change 写入 design.md	禁止
5. 制定计划	拆分为可执行任务	通过 openspec-continue-change 写入 tasks.md	禁止
6. 执行计划	按任务实施并勾选完成；所有任务完成后，调用 test-suite-ensure 确保测试套件已就绪	通过 openspec-apply-change 更新 tasks.md 复选框；测试文件（由 test-suite-ensure 生成）	允许
7. 检查与验证	测试、验证并对照产物交叉检查	通过 openspec-verify-change 技能或 openspec validate 得出验证结论	禁止
8. 评审与归档	落地结果或开始新一轮	通过 openspec-archive-change 技能更新 openspec/specs/ + 移入 openspec/changes/archive/	仅限归档/文档

阶段 1-5 禁止修改业务代码，但允许创建和更新 OpenSpec 产物。如果用户要求“只分析，不持久化”，则只输出各阶段结论，并跳过产物写入。

阶段 1：明确问题

⚠️ 主动提问：遵循 clarifying-question-discipline（每轮只问一个问题，进行多轮提问直至问题明确；先澄清，不要急于回答）。涉及领域术语时，还要遵循 domain-language-discipline。

领域路由：如果问题属于性能领域（缓慢 / 卡顿 / 资源增长），建议进入 perf-optimize-workflow——其证据门控范式适合该领域；其分析输出可以流转回此工作流（按此工作流，产物仍存放在 OpenSpec 中）。注意：其优化活动会创建每个项目专属的产物（基准测试日志 + 测试框架，以及预置的 code-insight / code-optimizer 技能）；优化-验证循环还需要环境循环运行器——分析阶段始终会运行。此内容仅供参考，不构成依赖项。

手动模式必须按顺序完成以下步骤：

1. 重述问题——用自己的话描述用户的问题。
2. 提取关键要素——目标、约束、背景、预期结果。
3. 列出待确认的问题——列出需要进一步确认的事项；如果要询问用户，每次只问一个最关键的问题，收到回答后再问下一个问题。 3.5. 拆分范围（如适用）——如果问题涉及多个相互独立的子系统，先帮助拆分：独立模块、依赖关系、建议的处理顺序——然后针对第一个子问题进入阶段 2 技术分析。
4. 等待用户确认。

工具限制：禁止使用 Read/Grep/SemanticSearch，但以下情况除外：

• 用户的消息中包含 @file-path（可选附行号）
• 用户粘贴了代码片段
• 用户明确指定了“函数 / 类名 + 其文件”的组合

符合例外情况时：只读取用户直接引用的文件和行，不得扩展到其他文件。读取结果只用于帮助理解问题——阶段 1 的输出不得包含技术分析结论。

手动模式的输出格式：参见 reference.md「阶段 1：明确问题」。

未经用户确认，不得创建变更或修改任何文件。确认后：

1. 使用 openspec-new-change 技能创建变更目录（读取其 SKILL.md，然后遵循其中的说明）。
2. 记录本轮选择的路径（完整 / 增量 / 精简）。
3. 然后进入阶段 2 技术分析。

自动模式可以跳过确认，但仍必须先生成候选名称，然后立即创建变更并继续。

阶段 2：分析问题

分析方法的唯一来源：analysis-core。此阶段不做实现变更——修复属于阶段 6。

委托给 analysis-core

加载强依赖 analysis-core 并执行其 §§1-3。本工作流中的映射（编号 + 名称）：

• {next-stage} = 阶段 3「探索解决方案」
• {root-cause step} = 步骤 5；{impact-assessment step} = 步骤 7；{upstream-eval step} = 步骤 6

🔌 OPSX：此阶段不创建任何产物；第 3 阶段选定解决方案后，Why / Impact 将写入 proposal.md。

阶段输出必须以分析门控输出块结尾（analysis-core §5 — 红环 / 调试入口 / 场景补充 / 临时变更）；缺少该块将阻止进入阶段 3。如果预期结果是用户可以看到或操作的内容，则在同一次加载中按 analysis-core 运行 competitive-research。不要重复说明其方法。

如果存在性检查失败或描述与代码不符，请暂停并等待用户确认，不要继续探索解决方案。

---

阶段 3：探索解决方案

原则：基于阶段 2 的分析，提出 2-5 个解决方案；从每个方案中剔除非必要功能和过度设计（YAGNI）。如果方向仍不明确，请先遵循 decision-fog-discipline，再编写方案表／提案。

架构边界预检（决策顺序）：当候选方案跨越进程或层级边界时，应先回答预检问题，再权衡短期成本（改动规模／复用／单仓库）——（1）运行时初始化位置：被调用的能力由哪个进程／层级初始化；（2）边界合法性：跨层导入是否会将被调用方的依赖树带入调用方的打包图（打包器静态预扫描会使动态 require/import 无法作为规避方案）；（3）所有权分类：系统能力、数据／产品能力，还是调用层的定位。边界判定结果应显示在比较表中，并用于把关自动模式的选择。方法论：code-design-review 的 A 层依赖方向维度。单层级方案无需进行此预检。

基于阶段 2 提出 2-5 个解决方案，每个方案都应包括：

• 核心思路
• 涉及的能力或行为变更
• 要添加或修改的 OpenSpec 能力
• 优点、缺点、复杂度、风险
• 推荐方案

在手动模式下，输出比较表，然后暂停，等待用户选择。

首次写入工件（proposal.md）之前，加载 git-worktree-discipline（工作树门禁 + 可选隔离）。

🔌 OPSX 技能集成：选定解决方案后，通过 openspec-continue-change 技能完成以下两个步骤（每次调用都会创建一个工件——先阅读其 SKILL.md，再按说明操作）：

1. 创建 proposal.md（变更的第一个就绪工件）：将阶段 2 的根因分析（Why / Impact）与本阶段的方案选择（What Changes / Capabilities）合并为完整提案。
2. 创建增量规范（提案完成后，规范即就绪）：将行为变更写入 specs/<capability>/spec.md。

增量规范约定（由 openspec-continue-change 技能强制执行）：

• 仅包含行为变更：## ADDED、## MODIFIED、## REMOVED、## RENAMED Requirements
• 每个需求标题都必须为 ### Requirement: <description containing SHALL or MUST>
• 每个需求都必须至少包含一个 #### Scenario: 区块

常见错误：### REQ-001:（格式错误）、### Requirement: Initialize（缺少 SHALL/MUST）、没有 Scenario 区块。 这三种情况都会导致 openspec validate 失败。格式示例见 openspec-continue-change 技能。

危险信号——阶段 3 禁止事项

• 只生成 1 个方案，并以“方向已经明确”为由跳过比较
• 在手动模式下，用户尚未选择方案就进入评审
• 方案包含非必要功能或过度设计（违反 YAGNI）

阶段 4：审查解决方案

加载 staged-review-flow 并执行其完整审查约定。本工作流的映射：{next-stage} = 阶段 5“制定计划”；{artifact-sink} = 通过 openspec-continue-change 创建的 design.md；{extra-dimensions} = 规范合规性（提案的原因、增量规范的行为、设计的风险、任务对需求的覆盖情况）；{batch-overcap-behavior} = N/A。审查通过后，通过原生技能创建 design.md。

非阻塞问题（可以作为建议提出，但不会阻碍通过；阻塞与非阻塞的判定标准由 solution-review 负责；对于代码解决方案，还由 code-design-review 负责——略微更好的架构如果不会显著提升长期可维护性，则不构成阻塞；但若存在明显更优且可行的方案，则构成阻塞，具体以这些技能为准）：

• 已有缓解措施的低风险事项
• 不影响正确性或结构的代码风格偏好
• 可推迟到后续迭代的非结构性性能改进
• 已明确接受且制定了偿还计划的 Prudent-Deliberate 技术债

阶段 4 的红线——禁止事项

• 跳过解决方案审查，直接进入阶段 5（风险尚未识别）
• 在审查阶段修改代码（违反只读约束）
• 自动模式审查失败后未优化解决方案，却仍进入阶段 5
• 自动模式审查循环超过 3 轮上限，且未暂停
• 自动模式优化解决方案时未记录优化理由，导致审查无法追溯
• 在手动模式下，用户尚未明确给出通过或不通过的判定，AI 就自行推进

阶段 5：制定计划

🔌 OPSX 技能集成：通过 openspec-continue-change 技能生成 tasks.md（先阅读其 SKILL.md，再遵循其中的说明；只有在规范和设计都完成后，任务才准备就绪）。该技能绝不会直接手动编写 tasks.md 内容。

tasks.md 约定（由技能强制执行）：

• 使用复选框；任务粒度要足够细；排序应体现依赖关系
• 包含必要的测试、验证、文档或迁移步骤
• 不得使用 TBD、TODO、“酌情处理”、“同上”或其他不可执行的描述

在手动模式下，输出计划并暂停；等待用户确认后再进入阶段 6。

阶段 6：执行计划

在修改生产代码之前，遵循 design-approval-gate（手动：用户通过；自动/精简：命名例外并留痕）。

上下文预算：根据 context-budget-discipline 评估阶段边界重置和压缩阈值（账本路径见阶段 5 的计划）；任何重置都必须先完整记录到账本中。

Figma 像素级保真： 当目标、卡片、问题或计划文本包含 figma.com 或 node-id=，或者用户要求像素级还原（像素级还原）时，加载 figma-pixel-implement 并遵循其要求。这些子串是范围依据。将这些行保持为硬性要求；不要因为任务还会检查行为，就把它们归入软性要求或人工检查项。探测可见文本、可见性标记或列表长度，均不能通过像素级要求。如果同一文本还包含 参考、match the existing 或 same as，则将该事实传入 verify，使指定控件的交互状态成为检查项。若目标仓库中没有持久化的清单和规范路径，则 Implement 不完整。在同一次运行中，该技能会继续执行 figma-pixel-verify，直至总体结果为 PASS，或测量命令无法运行。此处不要复述其方法。

阅读 tasks.md 并按顺序实施：

1. 每次只处理当前最小的一项任务。
2. 在接触业务代码之前，确认相关提案、规范、设计和任务文件均已存在。
3. 完成任务后立即更新复选框：使用 StrReplace 将 tasks.md 中对应的 [ ] 改为 [x]——不要等到一组任务完成后再批量更新。跳过此步骤会导致阶段 7 的验证器报告 CRITICAL 级别的错误未完成。
4. 如果实现过程中发现设计或规范不准确，先更新相应文档，再继续实现。
5. 说明任何偏离计划的原因；如果偏离影响范围或行为约定，则返回阶段 4 或阶段 5。

先测试，再确保测试套件（强制，执行报告前）

对于会改变行为的工作，遵循 test-first-discipline（先观察到测试失败，再编写生产代码）。tasks.md 中所有复选框都勾选后、输出执行报告前，必须执行以下步骤：

加载并调用 test-suite-ensure，声明 mode=mandatory，作用范围限定为此次变更的逻辑文件；若失败，或必要的脚手架请求被拒绝，则不得进入阶段 7。test-suite-ensure 不能替代测试优先实践。

🔌 OPSX 技能集成：调用 openspec-apply-change 技能执行任务（先阅读其 SKILL.md，然后按照其中的说明完成每项任务）。openspec-apply-change 会通过 CLI 内部查询变更状态和执行说明；该技能绝不会直接调用 CLI 来驱动执行。

阶段 7：检查与验证

上下文预算：如果发生了重置，则根据 context-budget-discipline 对照台账和产物进行验证；切勿重放先前会话的历史记录。

验证必须涵盖以下层面：

1. OpenSpec 验证：
   • 如果检测到 openspec-verify-change 技能 → 读取其 SKILL.md，并委派它进行验证。
   • 如果不存在 → 直接运行 openspec validate <change-name> 或 openspec validate --changes（调用 CLI 工具，不算降级）。

Node 版本对齐（前置条件）：在运行以下工程验证命令前，调用 node-version-discipline，使 Node 版本与项目声明的版本一致。

2. 工程验证：在版本对齐后，运行项目的测试、类型检查、Lint 或构建。
3. 行为交叉核对：逐条确认实现涵盖 delta-spec 中的所有要求和场景。
4. 调试验证循环：如果阶段 2 使用了调试技能来定位根本原因，则根据 analysis-core §4，使用同一技能验证修复（不能只靠测试）。
5. Figma 像素验证：当目标、卡片、问题或计划中包含 figma.com 或 node-id=，或本次运行是基于 Figma 实现时，加载 figma-pixel-verify 并遵循其要求；如果缺少测量报告（活动产物的 Verify 部分，或 Spec source 同级文件），则此验证阶段不能通过。Spec 缺口 FAIL 不算通过验证——应重新进入 figma-pixel-implement，补全表格。若用户/计划要求进行对齐检查，但本次运行没有实现任务，也要加载验证技能。只有当报告总体状态为 PASS（包括已接受的剩余问题），且其通道属于已完成布局的测量（storybook、isolated-harness、preview、full-app 或 layout-probe）时，此阶段才算通过。任何其他结果都表示此阶段失败，应返回实现阶段，再次修复并重新测量。此阶段还需运行 figma-pixel-verify 技能中的 scripts/check-figma-verify-report.mjs 检查该报告；非零退出码表示此阶段失败。不要重复说明其方法。

验证结论必须基于本轮实际运行且亲自阅读输出的命令；绝不能把“设计了一个场景”报告为“已通过”。

当本轮调度内容内联了冻结任务卡时，验证报告必须包含问题、原因、已完成的修复以及证据列表。每条证据必须是引用 png、jpg、jpeg 或 webp 路径的已打开 UI 检查，或引用命令并附简短输出摘要的非 UI 检查。缺失或为空的图片属于待处理项，并应注明仍需截图。不得编造图片。在用已打开的 UI 图片作为检查依据之前，必须根据 completion-evidence-discipline 检查该图片。本次运行不编写 HTML 页面，也不编写证据 HTML。

输出格式：参见 reference.md「阶段 7 检查与验证」。

根据 staged-review-flow 的验证报告诚信规则和 completion-evidence-discipline 为每项结果标注；没有本轮最新证据时，不得声称通过。

手动模式在此暂停，等待用户确认后再归档。验证失败时不得归档——应返回阶段 4、5 或 6。

测试执行

如果阶段 6 的执行报告涉及测试（单元测试、集成测试、手动验证步骤）：

验证执行遵循 runtime-verification-discipline（强依赖项）：AI 在环境中自行执行验证，只有遇到经分类确认的真正硬性限制时，才将某步骤交给用户，并说明原因。

• AI 可以执行：使用 Bash 运行测试命令（例如 npm test、pytest、go test），并将结果纳入检查结论。
• 否则：根据 runtime-verification-discipline 对阻塞因素分类；只有真正的硬性限制才可转为用户步骤，并说明原因。

阶段 8：审查与归档

如果验证通过，请运行归档前检查：

• tasks.md 中的所有事项是否都已完成？
• 增量规范是否反映了实际实现？
• 主规范是否会得到正确更新？
• 用户是否已确认归档？

🔌 OPSX 技能集成：归档前：

1. 如果存在增量规范：调用 openspec-sync-specs 技能（如果已安装），将增量规范合并到主规范 specs/<capability>/spec.md，或者让 openspec-archive-change 在归档期间提示并处理同步。
2. 执行归档：调用 openspec-archive-change 技能（先阅读其 SKILL.md，然后遵循其中的说明）。

如果 openspec-archive-change 失败，不要手动操作 openspec/ 目录——停止操作，并告知用户检查 OpenSpec 安装。

归档后，务必检查差异，确认主规范更新和归档目录移动都已反映在项目根目录的 git 工作树更改中。然后，如果本次运行可能需要提交和 PR/MR，则加载 delivery-discipline（归档差异通常需要交付；但该技能的 need-delivery 门控仍可能跳过）。接着加载 feature-branch-closeout，显示收尾选项（PR / 合并 / 保留 / 继续）。在测试尚未通过、归档尚未完成或差异尚未审查时，绝不要宣布完成。

顺序约束：归档 + 差异检查 → 可选的 delivery-discipline → feature-branch-closeout → 合并时，执行 merge-discipline A→B→C→R→D。选择保留/继续不会触发合并规范。

合并规范（merge-discipline 技能）

合并时（通过收尾流程或用户直接发出合并命令），加载 merge-discipline 并依次执行 Part A → B → C → R → D；合并前检查清单见 merge-discipline/reference.md。绝不要隐式跳过。

回顾（委托给 learn-and-improve）

归档和分支收尾完成后，加载 learn-and-improve 并遵循其框架；通过常规流程归档的 OpenSpec 工件不受其沉淀价值门控约束。

OpenSpec 工件（proposal.md、specs/、design.md、tasks.md）是此技能的核心交付物，通过常规归档流程落地——不受 learn-and-improve 的沉淀价值门控约束。 AI 工程知识（AGENTS.md、CLAUDE.md、.cursor/rules/、项目本地技能等）的沉淀价值判断和载体选择由 learn-and-improve 的决策树负责；只有在用户明确提出请求后才能编写。

归档后的输出格式：参见 reference.md「阶段 8：审查与归档」。

如果不适合归档，请保持更改处于活动状态，并说明阻碍因素和后续步骤。

常见错误

此处仅列出这项技能特有且不明显的陷阱。合并／覆盖率／固定提示 → merge-discipline；项目根目录／openspec/／原生技能门槛 → opsx-workspace-gate。阶段正文中已说明的规则不再重复。

错误	后果	修复方法
未确认手动模式就创建变更	违反阶段 1 的门槛，可能创建错误目录	阶段 0 只准备候选名称；确认后再创建
根因分析后立即创建提案（尚未选定解决方案）	Why／What 脱节，需要重写产物	阶段 3 选定解决方案后，再通过 openspec-continue-change 一次性创建提案
把旧名称或短名称当作通过门槛（例如 openspec-propose、openspec-apply）	根据过时的架构手写，或找不到其 SKILL.md	仅接受以下四个确切名称：openspec-new-change / openspec-continue-change / openspec-apply-change / openspec-archive-change（verify 可选）
MODIFIED 只写了一个片段	归档的需求会丢失原始内容	复制完整的需求块，然后再编辑
分支收尾选择“保留／继续开发”时仍运行覆盖率门槛	在非合并决策下错误触发门槛	只有在决策为“合并”时才触发门槛
在 ask 模式下或未配置时默认运行分析器	强制不需要覆盖率的项目通过门槛	参见 merge-discipline C 部分：先确定偏好——ask 必须先询问
等一组任务全部完成后才批量更新 tasks.md 复选框	验证器会报告 CRITICAL 级别的错误未完成	每项完成后立即将对应的 [ ] 改为 [x]
把“已设计一个场景”写成“验证通过”	用户会误信验证已通过	将每项标记为“已执行（命令 + 输出摘要）”或“待处理（需要采取行动）”
增量需求中没有 SHALL/MUST，或没有 Scenario	openspec validate 会持续失败	在描述中使用 SHALL/MUST；添加一个 #### Scenario:
根据假设的 DOM 而非实际观察到的状态编写浏览器断言	waitForFunction 超时	断言前先通过 evaluate 读取实际值

最低成功标准

一次完整运行至少必须生成或更新以下内容：

• openspec/changes/<change-name>/proposal.md
• openspec/changes/<change-name>/specs/<capability>/spec.md
• openspec/changes/<change-name>/design.md
• openspec/changes/<change-name>/tasks.md

完成时：

• 所有任务均已勾选。
• 已运行 test-suite-ensure：单元测试全部通过；端到端测试通过或已说明跳过原因。
• OpenSpec 验证通过。
• 项目验证通过，或已明确列出手动验证项目。
• 经用户确认后归档；或者保持变更处于活动状态，并说明不归档的原因。