create-yss-spec 3.3.4 → 3.3.6

package/template/.pi/skills/yss-implementation-contract-compiler/references/boundaries.md

@@ -18,6 +18,7 @@
 
 | Capability | Primary skill | Task modes |
 | --- | --- | --- |
+| `writing.lifecycle-document` | `i-have-adhd` | `guidance` |
 | `architecture.technical-design` | `yss-technical-design` | `guidance`, `integration`, `review-input` |
 | `architecture.mvc-design` | `yss-mvc-design` | `guidance`, `integration`, `review-input` |
 | `layer.mvc-service` | `yss-application` | `guidance`, `integration`, `slice-implementation`, `troubleshooting`, `review-input` |
@@ -105,8 +106,16 @@
 
 | Skill | Dependency | Type | Condition |
 | --- | --- | --- | --- |
+| `prototype-review` | `i-have-adhd` | `context-conditional` | `lifecycle-document-output` |
+| `yss-implementation-contract-compiler` | `i-have-adhd` | `context-conditional` | `lifecycle-document-output` |
+| `yss-openapi-governance` | `i-have-adhd` | `context-conditional` | `lifecycle-document-output` |
+| `yss-stage-decision` | `i-have-adhd` | `context-conditional` | `lifecycle-document-output` |
+| `yss-research` | `i-have-adhd` | `context-conditional` | `lifecycle-document-output` |
+| `yss-product-lifecycle` | `i-have-adhd` | `context-conditional` | `lifecycle-document-output` |
+| `code-review` | `i-have-adhd` | `context-conditional` | `lifecycle-document-output` |
 | `code-review` | `yss-repository` | `context-conditional` | `backend-persistence-impact` |
 | `code-review` | `yss-mybatis` | `context-conditional` | `backend-persistence-impact` |
+| `yss-prototype-stage` | `i-have-adhd` | `context-conditional` | `lifecycle-document-output` |
 | `yss-prototype-stage` | `prototype-review` | `review-only` | — |
 | `yss-prototype-stage` | `yss-design-system` | `coordination-only` | — |
 | `yss-prototype-stage` | `yss-antdv-next-design` | `context-conditional` | `h2-vue-antdv-next-default` |
@@ -118,6 +127,7 @@
 | `yss-domain` | `domain-modeling` | `coordination-only` | — |
 | `yss-domain` | `yss-tactical-design` | `context-conditional` | `tactical-domain` |
 | `yss-domain` | `lombok` | `context-conditional` | `pojo` |
+| `yss-technical-design` | `i-have-adhd` | `context-conditional` | `lifecycle-document-output` |
 | `yss-technical-design` | `yss-tactical-design` | `coordination-only` | `domain-driven` |
 | `yss-technical-design` | `yss-mvc-design` | `coordination-only` | `layered-mvc` |
 | `yss-mvc-design` | `yss-openapi-draft-review` | `review-only` | `api-impact` |

package/template/.pi/skills/yss-openapi-governance/SKILL.md

@@ -15,6 +15,12 @@ Spec / 设计输入 → OpenAPI YAML Draft → 审查与 Freeze → JSON 派生
 
 YSS DTO 的可复用 HTTP/JSON 映射由 `.agents/skills/yss-dto/references/openapi-wire-profile.yaml` 单一维护。它描述公开 wire shape，不是 Java 字段或 getter 清单；本 skill 必须消费 profile，不能在治理文档、feature YAML 和 JSON 中各自发明 `SingleResult`、`PageResult` 或 `PageQuery` 字段表。
 
+文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `docs/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。
+
+## 文档写作
+
+编写接口说明和契约评审交接正文前，读取 `docs/process/document-writing.md` 的共用写法及工程契约指引；协议标识、schema、冻结状态和验证记录按原合同保存。
+
 ## 边界与职责
 
 使用 `yss-openapi-governance`：

package/template/.pi/skills/yss-product-lifecycle/SKILL.md

@@ -7,6 +7,8 @@ description: 编排 YSS 产品或模块从机会调研到 Spec、原型、技术
 
 生命周期单一主控：识别请求、仓库身份和最近可信阶段，计算可执行 frontier，派发并验收工作单元；业务设计、实现和独立审查交给专项 skill。
 
+文档按 `document_writing` 条件调用 `i-have-adhd`，并传递 `docs/process/document-writing.md` 规范。
+
 ## 事实源与按需加载
 
 先读 `yss-project.yaml`、`CONTEXT.md`、相关 ADR、父 Ticket/checkpoint 和当前资产，按需加载合同子树：
@@ -25,7 +27,7 @@ description: 编排 YSS 产品或模块从机会调研到 Spec、原型、技术
 scripts/query-lifecycle-context --mode route --stage stage.plan --work-unit work-unit.plan-requirements --include execution_efficiency
 ```
 
-`--include` 接受编排合同的顶层键；非法模式、ID 或合同键必须失败。查询结果只是带摘要的权威事实投影，不成为新的事实源。解释性细节按需读取 `references/orchestration.md`、`references/state-model.md`、`references/artifact-dependencies.md`、`references/user-decisions.md` 和 `references/matt-yss-adapter.md`，达到最小充分证据后停止扩展上下文。
+`--include` 接受编排合同的顶层键；非法模式、ID 或合同键必须失败。结果为权威投影；细节按需读 `references/orchestration.md`、`references/state-model.md`、`references/artifact-dependencies.md`、`references/user-decisions.md` 和 `references/matt-yss-adapter.md`，证据充分即停止加载。
 
 按 `execution_efficiency` 合并查询、复用未变资料并验证当前资产；产品流转不重跑模板套件。词汇对账、恢复核验及门禁不变，执行细节见 `references/orchestration.md`。
 

package/template/.pi/skills/yss-product-lifecycle/references/orchestration-contract.yaml

@@ -1,4 +1,16 @@
 schema_version: 1
+document_writing:
+  supporting_skill: i-have-adhd
+  condition: lifecycle-document-output
+  scope: current-document-work-only
+  dispatch: pass-condition-and-reference-to-document-owner
+  reference: docs/process/document-writing.md
+  examples: docs/templates/examples/lifecycle-writing-examples.md
+  load_when: [lifecycle-document-draft, lifecycle-document-revision, progress-or-decision-presentation]
+  dispatch_input: include-reference-for-document-work
+  artifact_ownership: unchanged
+  gate_and_status_semantics: unchanged
+
 backend_architecture_identity_policy:
   source: docs/agents/yss-skill-registry.yaml#architecture_profiles
   schema: docs/process/schemas/backend-architecture-identity.schema.json

package/template/.pi/skills/yss-prototype-stage/SKILL.md

@@ -7,6 +7,12 @@ description: Use when a YSS feature has product-design impact on a primary flow,
 
 把产品设计影响收敛为跨 Agent 一致的原型交付物、证据和生命周期回流合同。它不替代 `yss-product-lifecycle` 的门禁裁决，也不把原型当作生产前端代码。
 
+文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `docs/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。
+
+## 文档写作
+
+起草或修订交互说明、状态说明和设计结论前，读取 `docs/process/document-writing.md` 的共用写法及产品设计指引；原型视觉和行为仍消费当前设计合同。
+
 ## 进入条件与主入口
 
 - 先由 `yss-product-lifecycle` 判断产品设计影响；无行为变化的孤立视觉修复记录 `not-applicable`，不创建空资产。

package/template/.pi/skills/yss-research/SKILL.md

@@ -9,6 +9,12 @@ Investigate facts that a YSS decision depends on. Produce evidence and bounded c
 
 `research` is a deprecated compatibility alias. Use `yss-research` in new assets and routing.
 
+文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `docs/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。
+
+## 文档写作
+
+撰写研究简报或结论前，读取 `docs/process/document-writing.md` 的共用写法和研究指引；既有证据结构、来源限定和校验器要求保持完整。
+
 ## Profiles
 
 - `technical-evidence`: standards, official documentation, source code, third-party APIs, framework behavior, protocols, or implementation constraints. Decision-bearing claims must trace to primary sources.

package/template/.pi/skills/yss-stage-decision/SKILL.md

@@ -7,6 +7,12 @@ description: 编排 Plan 到 Spec 入口的方案决策与业务边界、协作
 
 `yss-stage-decision` 是由生命周期主控调度的上游决策技能，负责把需求、产品、商务输入和业务边界与规则设计结果整理成可审查、可版本化、可被下游消费的方案决策包。它不替代生命周期主控，也不生成产品代码、原型、OpenAPI 或垂直切片 Ticket。
 
+文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `docs/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。
+
+## 文档写作
+
+撰写方案决策包和业务边界说明前，读取 `docs/process/document-writing.md` 的共用写法及 Plan 指引；原业务规则、决定依据和未决项完整保留。
+
 ## 适用边界
 
 - 适用于 `project-instance` 的 Plan → Spec 入口。

package/template/.pi/skills/yss-technical-design/SKILL.md

@@ -7,6 +7,12 @@ description: 在 YSS 技术分析中统一承接需求与战略输入，按已
 
 由 `yss-product-lifecycle` 调度，负责 `work-unit.technical-analysis` 的技术设计，不另起生命周期、不生成生产代码。生命周期维护批准和状态；`yss-implementation-contract-compiler` 消费批准且当前的设计，起草实现合同。
 
+文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `docs/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。
+
+## 文档写作
+
+起草或修订技术设计解释正文前，读取 `docs/process/document-writing.md` 的共用写法及工程契约指引，并在分支派发中传递该引用；结构化合同保持原 schema 和验证要求。
+
 ## 输入与架构选择
 
 先读根 `CONTEXT.md`、已批准且当前的 Spec、业务规则、关键场景、适用的 API 契约、ADR 和工程约束。没有 API 或其他专项影响时记录有依据的不适用，不生成占位设计。

package/template/docs/agents/yss-skill-registry.yaml

@@ -57,6 +57,7 @@ capability_contract:
     preserve_all_reasons: true
   deterministic_order: [recipe-declaration, dependency-topology, skill-id]
 capabilities:
+  - { id: writing.lifecycle-document, primary_skill: i-have-adhd, task_modes: [guidance] }
   - { id: architecture.technical-design, primary_skill: yss-technical-design, task_modes: [guidance, integration, review-input] }
   - { id: architecture.mvc-design, primary_skill: yss-mvc-design, architecture_family: layered-mvc, task_modes: [guidance, integration, review-input] }
   - { id: layer.mvc-service, primary_skill: yss-application, architecture_family: layered-mvc, task_modes: [guidance, integration, slice-implementation, troubleshooting, review-input] }
@@ -110,10 +111,24 @@ recipes:
   - { id: frontend.vue3-scaffold, capabilities: [scaffold.frontend-vue3] }
   - { id: backend.springboot3-migration, capabilities: [migration.springboot3, quality.java-code-style] }
 skill_dependencies:
+  prototype-review:
+    - { skill: i-have-adhd, type: context-conditional, when: lifecycle-document-output }
+  yss-implementation-contract-compiler:
+    - { skill: i-have-adhd, type: context-conditional, when: lifecycle-document-output }
+  yss-openapi-governance:
+    - { skill: i-have-adhd, type: context-conditional, when: lifecycle-document-output }
+  yss-stage-decision:
+    - { skill: i-have-adhd, type: context-conditional, when: lifecycle-document-output }
+  yss-research:
+    - { skill: i-have-adhd, type: context-conditional, when: lifecycle-document-output }
+  yss-product-lifecycle:
+    - { skill: i-have-adhd, type: context-conditional, when: lifecycle-document-output }
   code-review:
+    - { skill: i-have-adhd, type: context-conditional, when: lifecycle-document-output }
     - { skill: yss-repository, type: context-conditional, when: backend-persistence-impact }
     - { skill: yss-mybatis, type: context-conditional, when: backend-persistence-impact }
   yss-prototype-stage:
+    - { skill: i-have-adhd, type: context-conditional, when: lifecycle-document-output }
     - { skill: prototype-review, type: review-only }
     - { skill: yss-design-system, type: coordination-only }
     - { skill: yss-antdv-next-design, type: context-conditional, when: h2-vue-antdv-next-default }
@@ -129,6 +144,7 @@ skill_dependencies:
     - { skill: yss-tactical-design, type: context-conditional, when: tactical-domain }
     - { skill: lombok, type: context-conditional, when: pojo }
   yss-technical-design:
+    - { skill: i-have-adhd, type: context-conditional, when: lifecycle-document-output }
     - { skill: yss-tactical-design, type: coordination-only, when: domain-driven }
     - { skill: yss-mvc-design, type: coordination-only, when: layered-mvc }
   yss-mvc-design:
@@ -198,6 +214,11 @@ invocation_contract:
       invocation_mode: user
       primary_output: maintenance-operation
   overrides:
+    i-have-adhd:
+      invocation_mode: model
+      trigger_conditions: [lifecycle-document-output]
+      exclusion_conditions: [code-only-work, command-only-work, unrelated-conversation, user-disabled]
+      primary_output: document-writing-assistance
     yss-prototype-stage:
       invocation_mode: both
       trigger_conditions: [impact:prototype]
@@ -218,6 +239,7 @@ agent_runtime_roots:
   cursor: .cursor/skills
   pi: .pi/skills
 skills:
+  - { id: i-have-adhd, layer: core, maturity: supported, instance_default_discoverable: true, aliases: [], impacts: [writing] }
   - id: alibaba-java-code-style
     layer: specialist
     maturity: supported

package/template/docs/plan/templates/plan-template.md

@@ -9,18 +9,22 @@ owner: <负责人>
 
 > 生命周期身份：`stage.plan` / `artifact.plan-record`。按影响面填写，不制造未命中项的空产物。进入 Spec 的退出条件以 `docs/process/lifecycle-registry.yaml` 为准。
 
-## 1. 输入与复用依据
+填写前读取[中文写作规范](../../process/document-writing.md)和 [Plan 对照](../../templates/examples/lifecycle-writing-examples.md#1-plan让业务问题和取舍可见)。先说明问题和本期取舍，假设与事实分开；以下各项按实际影响填写。
 
-| 资产 / 证据引用 | 版本 | 本次仍有效的依据 | 需要重新探索的部分 |
-|---|---|---|---|
+## 1. 用户、问题与目标
 
-## 2. 用户、问题与目标
+用一段话说明谁在什么情境下遇到什么问题、本期建议改变什么；收益未经验证时保持候选语气。
 
 - 目标用户和关键业务故事：
 - 问题、为什么现在做：
 - 期望结果、成功标准及验证方式：
 - 约束、假设及事实证据：
 
+## 2. 输入与复用依据
+
+| 资产 / 证据引用 | 版本 | 本次仍有效的依据 | 需要重新探索的部分 |
+|---|---|---|---|
+
 ## 3. 战略资产引用
 
 | 权威资产 | 当前版本 / 引用 | 确认状态 / 未命中原因 |

package/template/docs/process/document-writing.md

@@ -0,0 +1,77 @@
+# 研发文档中文写作规范
+
+起草或修订生命周期文档时，先读本规范的共用写法，再按阶段查阅第 3 节；发送进度与会签提示时读取第 4 节。按当前写入范围应用，正文、摘要和结构化信息应保持同一语义。
+
+[Plan、Spec、Ticket 写作对照](../templates/examples/lifecycle-writing-examples.md)提供同一事实输入下的改写样例；示例不构成真实需求或批准。
+
+## 1. 适用范围与保留项
+
+适用于研究结论、Plan、Spec、产品设计说明、工程契约的解释正文、Ticket、审查、发布和复盘。聊天中的进度通知按第 4 节处理。
+
+本文件是生命周期文档的共用写作规范。生命周期身份、门禁、资产所有权、批准和状态由根 `AGENTS.md` 指定的权威资产决定；标准术语消费根 `CONTEXT.md`。本规范约束表达，不新增阶段、审批或业务规则。
+
+写作调整应保留这些内容的原意：主体、触发条件、规则、例外、量词、范围、非目标、数值及单位、证据引用、未决项、责任人、时点和依赖。稳定 ID、API 标识、schema、metadata、版本及批准记录按原合同保存。已经冻结的内容若需要改变行为，应回交资产所有者处理，不作为润色顺手修改。
+
+## 2. 共用写法
+
+### 先回答读者当前需要判断的问题
+
+开头说明业务问题、本次结论或交付行为。必要背景紧接其后，让读者知道结论为什么成立。正式模板要求的 metadata 和身份信息仍保留；表达顺序的建议不能自行覆盖校验器要求的结构。
+
+只在内容较长或需要导航时添加摘要。摘要引用正文，不另写一套范围和状态；维护时检查二者一致。
+
+### 用主体、条件和结果表达需求
+
+把“提升效率”“完善体验”等目标落实到具体场景：谁在什么情况下做什么，系统产生什么可观察结果。保留支持判断的业务动机，不把所有文字都拆成短句或编号。
+
+输入没有规则时，记录待确认问题；不要为了让句子具体而补出时限、阈值、错误码或默认行为。重要缺口交回拥有该决定的工作单元。非阻断细节按既有流程记录责任人、解决时点和接收方。
+
+### 让确定程度与证据一致
+
+事实给出处；推断说明依据；方案使用建议语气；假设写明如何验证。章节开头已明确整段是假设或建议时，无须每句重复标签。
+
+保留表达真实不确定性的“尚未确认”“可能”“取决于”。只有测试失败现象时，报告现象和下一项诊断，不编造原因；只有期望收益时，写目标和验证方法，不写成已实现收益。估算需有执行者、依据、范围和条件；无依据时不填精确工期。
+
+### 让每段承担一项用途
+
+一段解释一个问题、一项规则或一个取舍。顺序动作使用编号；同类规则、状态或选项比较使用表格；因果和取舍使用连贯段落。列表长度、段落数量和总字数按内容决定。
+
+删除只有态度、没有事实或决定的修饰句。技术术语、业务术语和必要限定词保持准确，不使用同义词轮换制造变化。评价文档看它是否明确、可信和可执行，不追求模拟人的口头习惯或降低 AI 检测分数。
+
+### 复用上游事实，交代本阶段新增内容
+
+引用上游规则的可定位位置和必要版本，本阶段写新增细化、适用范围和交接。直接决定本地验收的条件可以在场景中重述，并绑定同一规则 ID；以一致性核验控制漂移。
+
+不要用“详见相关文档”代替必要信息。引用不可读或版本不明时按现有合同处理。条件项只在流程允许时记录带原因的 `not-applicable`；命中的要求和必要异常场景应完整展示。
+
+## 3. 各阶段怎么写
+
+| 阶段 | 正文优先回答 | 本阶段需要写具体的内容 |
+|---|---|---|
+| 研究 | 已知什么，证据支持到哪里？ | 结论与来源、反证、限制分开；建议与事实区分 |
+| Plan | 谁遇到什么问题，本期为什么这样取舍？ | 业务故事、MVP / 非目标、优先级依据、成功标准的确认情况、关键未决项 |
+| Spec | 什么条件下，系统必须怎样表现？ | 规则与验收对应；按影响面覆盖成功、拒绝、边界、状态变化和恢复 |
+| 产品设计 | 用户如何完成任务，失败后如何继续？ | 入口、操作、反馈、状态和恢复路径；引用 Spec，保留设计待确认项 |
+| 工程契约 | 实现必须遵守什么，哪些地方有取舍？ | 精确协议与解释正文配合；标识、版本、范围及约束保持可核验 |
+| Ticket | 本切片交付什么，如何证明完成？ | 窄而完整的行为、依赖、验收、公共测试 seam、当前合同及验证证据 |
+| 审查 | 哪个具体条件下存在什么问题？ | 定位、触发条件、影响、依据与修复建议；推测和已复现问题分开 |
+| 发布 / 复盘 | 验证了什么，还剩什么风险或决定？ | 实际验证范围、未覆盖部分、发布决定或失误机制与改进行动 |
+
+这些指引帮助填写既有模板，不新增必填字段、阶段或门禁。Plan 不提前承诺详细 API 和工程实现；Spec 的例子不代替完整规则；Ticket 不重新设计已冻结行为。
+
+## 4. 进度与会签提示
+
+进度更新说明本轮有意义的变化、当前阻塞和接下来由谁处理。状态没有变化时，无须重述全部计划。已授权且 Agent 可以完成的动作继续执行，避免把操作转交用户。
+
+请求决定时展示当前版本、推荐方案及理由、实质选项和取舍、风险、批准范围与后续动作，遵守既有用户决定协议。可以突出当前最重要的问题，但所有影响决定的阻塞和选项都应可见。一次回复需要多个相互独立的决定时，分别说明各自影响。
+
+示例：“规则说明已补齐。成功标准仍缺统计口径，负责人需在 Plan 进入 Spec 前确认；当前材料尚不能支持流转。”这类表述需要实际资产支持，不能成为固定的完成话术。
+
+## 5. 起草与修订时的检查
+
+1. 确认文档读者、当前阶段、权威输入和允许改动的范围；区分从事实起草与对既有正文作等义改写。
+2. 起草时按本阶段的问题组织内容；修订时先列出必须保留的规则和约束，再调整文字。
+3. 对照输入检查有无新增承诺、规则丢失、范围扩大、责任转移或不确定性被抹去。发现源资产冲突时记录并回交，不自行选一个版本。
+4. 检查正文、摘要、表格和状态是否一致；验证适用的引用、结构和合同。自检结论不代替独立审查或批准。
+
+规则、例外、证据或状态变化属于实质差异，不能被“字数减少”抵消。不要只用禁用词扫描或模型给自己的分数判断效果。

package/template/docs/templates/examples/lifecycle-writing-examples.md

@@ -0,0 +1,138 @@
+# Plan、Spec、Ticket 写作对照
+
+性质：虚构的写作示例，非产品资产，不代表业务术语或批准记录。
+
+本文件配合[中文写作规范](../../process/document-writing.md)。每组先给固定输入，再给两种表达，最后逐项核对。三组独立提供事实，不表示真实项目已经从 Plan 进入 Spec 或取得任何批准。“原写法”由作者构造，不是对模型运行结果或真实文档的抽样。
+
+## 1. Plan：让业务问题和取舍可见
+
+### 固定输入
+
+| 示例编号 | 已提供信息 |
+|---|---|
+| P1 | 示例访谈中，一名采购申请人说申请曾因缺少材料被退回；未提供访谈记录或样本统计 |
+| P2 | 本期候选范围是在提交前检查必填附件，并指出缺少的材料；业务价值尚待验证 |
+| P3 | 材料真实性识别、审批路线调整不在本期范围 |
+| P4 | 建议用缺材料退回比例观察效果；基线、统计口径和目标值尚未确认 |
+| P5 | 必填材料清单尚未确认，影响关键业务规则；需求经理需在进入 Spec 前取得业务负责人确认，并交接给 Spec 起草者 |
+| P6 | 当前范围及成功标准仍待用户确认，本组示例不能支持 Plan 流转 |
+
+### 原写法：事实齐全，但结论被修饰语遮住
+
+为全面提升采购协作体验，本阶段拟通过前置校验能力构建高效闭环，实现申请质量的持续优化。一名申请人在示例访谈中提到材料缺失导致退回，但尚无访谈原始记录及统计数据。规划提交前检查必填附件并提示缺少材料，业务价值待验证；材料真实性识别和审批路线调整不纳入本期。建议围绕缺材料退回比例建立成效评估体系，相关基线、统计口径和目标值有待明确。必填清单影响关键业务规则，由需求经理在进入 Spec 前取得业务负责人确认并交给 Spec 起草者；范围和成功标准也待用户确认，当前不能流转。
+
+### 改写：按问题、范围和未决决定组织
+
+本期建议在采购申请提交前检查必填附件，直接告诉申请人缺少哪些材料。
+
+问题线索来自一名申请人对材料缺失退回的描述；目前没有原始访谈记录和统计数据，尚不能判断问题发生频率或预期收益。
+
+本期不做材料真实性识别，也不调整审批路线。建议观察缺材料退回比例是否下降；统计口径、基线和目标值仍待确认。
+
+进入 Spec 前，需求经理需要取得业务负责人对必填材料清单的确认，并交给 Spec 起草者。清单影响关键业务规则；当前范围和成功标准也未取得用户确认，因此本组规划尚不能流转。
+
+### 保真核对
+
+| 输入 | 改写落点 | 保留语义 |
+|---|---|---|
+| P1 | 问题线索段 | 保留单一样本和来源缺口，没有改写成普遍问题 |
+| P2 | 首段及问题线索段 | 范围保持候选语气，没有承诺已验证收益 |
+| P3 | 非目标句 | 两项非目标均保留 |
+| P4 | 指标句 | 基线、口径、目标均未凭空补值 |
+| P5 | 最后一段 | 保留关键程度、负责人、确认方、时点和接收方 |
+| P6 | 最后一句 | 未将文字完善解释为可以流转 |
+
+## 2. Spec：让规则可以转成验收
+
+### 固定输入
+
+以下是假设已由业务提供的七条规则，用于独立演示；它们不是从上一组待确认的 Plan 自动推导的决定。
+
+| 示例编号 | 已提供信息 |
+|---|---|
+| S1 | 校验发生在申请人点击提交时 |
+| S2 | 缺少任一必填附件时，拒绝提交，申请保持草稿 |
+| S3 | 逐一列出所有缺少附件的名称，不只显示第一项 |
+| S4 | 校验拒绝后，保留本次页面已填写内容；未承诺关闭或刷新页面后仍保留 |
+| S5 | 补齐附件后，再次提交时重新校验 |
+| S6 | 附件齐全且其他既有提交条件通过时，沿用既有提交流程；附件齐全本身不保证提交成功 |
+| S7 | 不检查材料真实性；必填清单读取失败时如何处理尚未确认，交业务负责人在 Spec 冻结前确认 |
+
+### 原写法：规则挤在一段中
+
+系统应提供完善的附件校验能力和友好的异常反馈。在申请人点击提交时进行检查，缺少任一必填附件即拒绝并保持草稿，完整列出所有缺少附件名称，且保留本次页面输入，但不保证刷新或关闭页面后保留。补齐后再次提交需重新校验，只有附件齐全且其他既有条件也通过才能沿用既有流程，附件齐全不能单独保证成功。不校验材料真实性；清单读取失败行为尚未明确，需业务负责人在 Spec 冻结前确认，以保障整体体验。
+
+### 改写：规则和例子对应
+
+申请人点击提交时，系统检查必填附件。缺少任一附件即拒绝提交，申请保持草稿，并逐一列出所有缺少附件的名称。
+
+| 条件 / 操作 | 可观察结果 | 对应输入 |
+|---|---|---|
+| 缺少任一必填附件，点击提交 | 拒绝提交；申请仍为草稿；列出全部缺失名称 | S1、S2、S3 |
+| 因附件缺失被拒绝 | 本次页面已填写内容仍在；不承诺刷新或关闭后的保存 | S4 |
+| 补齐附件后再次点击提交 | 重新执行附件校验 | S5 |
+| 附件齐全且其他既有条件通过 | 进入既有提交流程 | S6 |
+
+附件齐全不代表其他提交条件已经通过。本功能不检查材料真实性。
+
+验收例子：在示例清单中，“报价单”和“采购说明”均为必填，申请人两项都未提供。点击提交后，应看到两个缺失名称，申请仍为草稿，当前页面已填写内容保留。这里的附件名称是测试数据，不扩展实际必填清单。
+
+待确认：必填清单读取失败时的行为，由业务负责人在 Spec 冻结前确认。当前不能将失败默认解释为放行或拒绝。
+
+### 保真核对
+
+| 输入 | 改写落点 | 保留语义 |
+|---|---|---|
+| S1、S2 | 首段、首行条件 | 触发点和状态保持不变 |
+| S3 | 首段、首行结果、验收例子 | “所有”未缩为一项，没有五项展示上限 |
+| S4 | 第二行结果 | 页面内保留未扩展成持久保存 |
+| S5 | 第三行 | 保留再次校验 |
+| S6 | 第四行及后续限定句 | 保留与其他条件的合取关系 |
+| S7 | 非目标与待确认段 | 未新增真实性检查，也未决定故障降级行为 |
+
+本例比原文更长，增加的是规则之间的边界和定位信息；这不构成效果退步。
+
+## 3. Ticket：把交付行为与实现就绪区分清楚
+
+### 固定输入
+
+| 示例编号 | 已提供信息 |
+|---|---|
+| T1 | 切片交付“提交申请时校验必填附件并展示拒绝结果”，覆盖所需前后端行为，不以技术层横拆 |
+| T2 | 示例内给定 Spec v2 的规则 R1 和 OpenAPI v3 已冻结；它们只是虚构输入标签，没有真实批准记录 |
+| T3 | 验收覆盖缺失时拒绝且不提交、全部缺失名称可见、页面输入保留，以及补齐后重新校验 |
+| T4 | 公共测试 seam 是提交接口和申请表单交互；命令应从真实工程与实现合同读取，示例未提供命令 |
+| T5 | Slice Implementation Contract v1 仍为草案、生命周期批准 pending；依赖的必填材料配置切片未完成 |
+| T6 | 当前 Ticket 状态为 ready-for-human；不存在实现或测试通过证据；真实性识别不在范围内 |
+
+### 原写法：重点埋在实现名词之后
+
+本任务将全面完善前后端附件校验链路，覆盖提交接口、页面交互及相关测试，遵循示例 Spec v2 / R1 和冻结 OpenAPI v3，以端到端切片交付提交申请时的必填附件校验及拒绝反馈，不按技术层横拆。需验证缺失拒绝且不提交、完整提示缺失名称、保留页面输入和补齐后重新校验；公共 seam 为提交接口与申请表单，命令需读取工程和合同。实现合同 v1 为草案且批准 pending，必填材料配置依赖尚未完成。状态 ready-for-human，尚无实现或测试通过证据，真实性识别不在范围。
+
+### 改写：先说交付，再列验收和阻塞
+
+本切片交付：申请人提交申请时，系统校验必填附件，并在拒绝提交后展示缺失材料。交付覆盖所需前后端行为。
+
+范围依据：示例 Spec v2 / R1、冻结 OpenAPI v3；材料真实性识别不在本切片范围。
+
+验收项均待验证：
+
+- [ ] 缺少必填附件时拒绝提交，申请未提交。
+- [ ] 页面列出全部缺失附件名称。
+- [ ] 拒绝后保留本次页面已填写内容。
+- [ ] 补齐后再次提交，重新执行附件校验。
+
+通过提交接口和申请表单交互验证以上行为。具体命令待从真实工程与实现合同读取，当前没有实现或测试通过证据。
+
+当前状态：`ready-for-human`。实现合同 v1 为草案，生命周期批准为 `pending`；必填材料配置切片也未完成。两项阻塞均需闭合，并由生命周期完成全部适用就绪核验后，才可决定是否进入实现。
+
+### 保真核对
+
+| 输入 | 改写落点 | 保留语义 |
+|---|---|---|
+| T1 | 首段 | 保留完整用户行为和跨受影响层范围 |
+| T2 | 范围依据 | 沿用示例版本，不产生真实批准 |
+| T3 | 四条未勾选验收 | 四项均保留，未伪造完成 |
+| T4 | 验证段 | seam 明确，未臆造工程命令 |
+| T5 | 状态段 | 两项阻塞均展示，未只保留一个下一步 |
+| T6 | 范围、验证及状态段 | 状态未提前推进；未扩大范围 |

package/template/docs/templates/spec-template.md

@@ -7,17 +7,19 @@ owner: ai
 
 # 产品研发规格：<功能名称>
 
+填写前读取[中文写作规范](../process/document-writing.md)和 [Spec 对照](examples/lifecycle-writing-examples.md#2-spec让规则可以转成验收)。保留原规则、例外和不确定性；输入缺失时记录待确认项。
+
 ## 功能父 Ticket
 
 <Local：`docs/.scratch/<feature>/parent-ticket.md`；GitHub / GitLab：Issue URL / 编号>
 
 ## 问题陈述
 
-（从用户视角描述要解决的问题。）
+（说明哪个角色在什么场景遇到什么问题，给出来源及其限制。）
 
 ## 解决方案
 
-（从用户视角描述解决方案。）
+（说明本次改变的用户行为和范围，区分已确认规则与候选方案。）
 
 ## 用户故事
 
@@ -25,12 +27,16 @@ owner: ai
 
 ## 功能需求
 
+需求写明主体、触发条件和可观察结果；关联验收标准。不要用“完善、友好、高效”代替规则。
+
 | ID | 需求 | 优先级 | 备注 |
 |---|---|---|---|
 | FR-001 | | P0/P1/P2 | |
 
 ## 非功能需求
 
+命中时填写工作负载或适用条件、目标值及单位、验证方式与依据；尚未确认的目标保留为未决项，不补造性能承诺。
+
 | 类别 | 需求 | 目标 |
 |---|---|---|
 | 性能 | | |
@@ -38,6 +44,8 @@ owner: ai
 
 ## 验收标准
 
+关联需求 ID，按实际影响覆盖成功、拒绝、边界和恢复。保留“全部”“仅当”等限定；测试数据不能反向扩展业务规则。
+
 ```gherkin
 假如 <上下文>
 当 <操作>
@@ -47,7 +55,8 @@ owner: ai
 ## 产品总体设计 / 功能架构
 
 - 功能域与模块边界：
-- MVP / 非目标：
+- MVP：
+- 非目标：见本文“非目标范围”，此处不重复维护。
 - UI 影响：是 / 否
 - 产品总体设计：`docs/.scratch/<feature>/design/<feature>-product-overview-design.md`
 
@@ -99,4 +108,8 @@ owner: ai
 
 ## 非目标范围
 
+明确本次不交付什么及依据；与上游范围保持一致。
+
 ## 风险
+
+记录已知风险和未决项的影响、责任人、解决时点及接收方；尚未明确原因时保留现象和验证方法。

package/template/docs/templates/vertical-slice-ticket-template.md

@@ -4,7 +4,7 @@ status: ready-for-human
 
 # 垂直切片 Ticket：<标题>
 
-Status: ready-for-human
+填写前读取[中文写作规范](../process/document-writing.md)和 [Ticket 对照](examples/lifecycle-writing-examples.md#3-ticket把交付行为与实现就绪区分清楚)。状态只在 frontmatter 维护，正文记录依据。
 
 ## 父级
 
@@ -14,6 +14,8 @@ Status: ready-for-human
 
 描述本 Ticket 要交付的窄而完整的端到端行为。它必须贯穿所有受影响层，是可独立验证的垂直切片，不能只是某一层的横向任务。
 
+先用一句话写出用户操作及交付结果，再引用对应 Spec 规则、版本和本切片边界；不要重写冻结需求或填入未经确认的范围。
+
 ## 覆盖的用户故事
 
 - <用户故事 ID 或文本>
@@ -31,6 +33,8 @@ Status: ready-for-human
 
 ## 验收标准
 
+每项写条件、操作和可观察结果，关联上游规则；保留必要例外。测试未执行前保持未勾选。
+
 - [ ] 标准 1
 - [ ] 标准 2
 - [ ] 标准 3
@@ -92,7 +96,7 @@ Status: ready-for-human
 
 ## 阻塞关系
 
-- 无，可立即开始
+列出实际依赖、未决项、责任人和解除条件；尚未核验时写“待核验”。只有确认没有阻塞时才写“无”，无依赖不等于已通过实现就绪核验。
 
 ## 重路由状态
 
@@ -116,9 +120,9 @@ Status: ready-for-human
 
 ## 状态
 
-`ready-for-agent`
+状态依据：<当前版本合同、批准和就绪核验记录引用，以及尚未关闭的阻塞>。
 
-> 仅当阻塞关系为“无”且必要门禁已通过时填写 `ready-for-agent`；否则写明被哪个 Ticket 阻塞。
+> 默认 frontmatter 为 `ready-for-human`。仅在生命周期确认合同已批准且当前、阻塞已清除、全部适用门禁及就绪条件通过后更新为 `ready-for-agent`；本节不另维护第二个状态值。
 
 ## AI / 人工审查点