universal-dev-standards 6.6.0 → 6.7.1

package/bundled/ai/standards/ai-response-navigation.ai.yaml

@@ -3,13 +3,14 @@
 
 id: ai-response-navigation
 meta:
-  version: "1.2.0"
+  version: "1.3.0"
   updated: "2026-08-17"
   source: core/ai-response-navigation.md
   description: >
     Every substantive AI response must include contextual next-step suggestions with recommended
-    options (rules 1-6, required). Optional rules 7-9 govern the answer itself: lead with the
-    finding, restate state across turns, no preamble.
+    options (rules 1-6, required). Optional rules 7-11 govern the answer itself: lead with the
+    finding, restate state across turns, no preamble, plain language as the subject, and a
+    trade-off on every option rather than only the recommended one.
 
 rules:
   - id: navigation-footer
@@ -116,6 +117,32 @@ rules:
       Does NOT apply to closers: navigation-footer still stands.
     priority: optional
 
+  - id: plain-language-is-the-subject
+    trigger: any response explaining a situation, a defect, or a system's behaviour to a human
+    instruction: >
+      Explain what happened in the words the reader would use. File paths, symbol names, line
+      references, command output and version strings are support: they belong after the sentence
+      they support, not as the sentence itself. This does NOT license omitting them — a reader who
+      wants to verify must be able to. It governs which of the two is the subject.
+      Distinct from lead-with-the-finding: that rule orders finding before evidence, this one
+      governs register. A response can lead with its finding and still state that finding in
+      vocabulary only its author holds; both leave the reader unable to act.
+    priority: optional
+
+  - id: every-option-carries-its-trade-off
+    trigger: a response asking the reader to choose between two or more courses of action
+    instruction: >
+      recommendation-marking requires marking the recommended option and giving ITS reason. This
+      extends that to the rest: each option states what it buys and what it costs, in its own terms.
+      A list where only the recommendation is argued hands the comparison back to the reader, which
+      is the work they asked to have done; and an option shown without its downside reads as having
+      none. A trade-off is not a hedge — "this may be slightly harder" is not a cost, "this rewrites
+      110 files and needs a human to check the translations" is. If an option genuinely has no
+      downside worth stating, say so explicitly: an empty cell reads as "not analysed" and the
+      reader cannot tell those apart. Composes with adaptive-quantity — trade-offs make each option
+      costlier to read, so the 1-5 cap matters more, not less.
+    priority: optional
+
 related_standards:
   - ai-command-behavior
   - ai-instruction-standards

package/bundled/core/ai-response-navigation.md

@@ -2,7 +2,7 @@
 
 > **Language**: English | [繁體中文](../locales/zh-TW/core/ai-response-navigation.md) | [简体中文](../locales/zh-CN/core/ai-response-navigation.md)
 
-**Version**: 1.2.0
+**Version**: 1.3.0
 **Last Updated**: 2026-08-17
 **Applicability**: All projects using AI-assisted development
 **Scope**: universal
@@ -19,11 +19,12 @@ This standard defines navigation behavior for AI responses: every substantive AI
 
 **Solution**: A standard "Navigation Footer" appended to every substantive AI response, with contextual templates, recommendation marking, and adaptive option quantities.
 
-**Scope note (v1.2.0)**: Rules 1–6 govern what comes *after* the answer. Rules 7–9 — added in 1.2.0
-and **optional** — govern the answer itself: lead with the finding, restate state across turns, no
-preamble. They were added because a response can satisfy every one of Rules 1–6 while burying its
-conclusion, and a reader who cannot find the answer is not helped by a correct footer telling them
-what to do next.
+**Scope note (v1.2.0, extended in 1.3.0)**: Rules 1–6 govern what comes *after* the answer.
+Rules 7–11 — **all optional** — govern the answer itself: lead with the finding (R7), restate state
+across turns (R8), no preamble (R9), plain language as the subject (R10), and a trade-off on every
+option rather than only the recommended one (R11). They exist because a response can satisfy every
+one of Rules 1–6 while burying its conclusion, stating it in vocabulary only its author holds, or
+listing options the reader still has to compare themselves.
 
 ---
 
@@ -103,9 +104,11 @@ Tier names are **vendor-neutral**. Each tool or platform maps these tiers to its
 
 ---
 
-## The Answer Before the Navigation (Rules 7–9, Optional)
+## The Answer Before the Navigation (Rules 7–11, Optional)
 
-> **Borrowed from**: [`ayghri/i-have-adhd`](https://github.com/ayghri/i-have-adhd) (MIT), 3 of its 10 rules.
+> **R7–R9 borrowed from**: [`ayghri/i-have-adhd`](https://github.com/ayghri/i-have-adhd) (MIT), 3 of its 10 rules.
+> **R10–R11 added in 1.3.0** from a different source — a user telling the author, twice in one session,
+> that a correct and complete answer was unreadable. R7–R9 had already shipped and were being followed.
 > The other 7 were dropped: 2 are already covered by Rules 1–2 above, and 5 either conflict with
 > this standard (its "no recap / no closers" contradicts Rule 1's Navigation Footer; its
 > "cap lists at 5" would truncate evidence tables and traversal denominators) or duplicate
@@ -116,7 +119,7 @@ itself — a response could bury its conclusion under a wall of evidence and sti
 in this standard by appending a correct Navigation Footer. A reader who cannot find the answer is
 not helped by being told what to do next.
 
-**These three rules are optional**, in the same sense as Rule 6: adopting projects are not required
+**These five rules are optional**, in the same sense as Rule 6: adopting projects are not required
 to enable them, and existing skills need no retroactive update. A project MAY promote any of them to
 required in its own configuration. What is *not* optional is that they have precise triggers — a rule
 phrased so loosely that it never fires is indistinguishable from not having the rule.
@@ -164,6 +167,53 @@ but the delay it puts between the reader and the answer.
 **Rule 9 does not apply to closers.** Rule 1 requires a Navigation Footer, and that requirement
 stands — the end of a response is where this standard puts the reader's next move.
 
+### Rule 10: Plain Language Is the Subject; Identifiers Are Support （Optional）
+
+**Trigger**: any response explaining a situation, a defect, or a system's behaviour to a human.
+
+Explain what happened in the words the reader would use. File paths, symbol names, line
+references, command output and version strings are **support** — they belong after the sentence
+they support, not as the sentence itself.
+
+| Instead of | Write |
+|-----------|-------|
+| "`load_topics()` at `intel-scout.py:883` reads `intel-topics.yaml`, while `load_feeds()` at `:1033` reads `intel-feeds.yaml`." | "It gathers material two ways: by searching keywords, and by subscribing to a fixed set of blogs." *(then cite both call sites)* |
+| "`manifest.skillHashes` has 137 entries keyed by `claude-code/project/<n>/SKILL.md` while the lookup uses `.claude/skills/<n>`." | "The hashes are stored under one naming scheme and looked up under another, so none are ever found." *(then show both keys)* |
+
+This is **not** a licence to omit the identifiers — a reader who wants to verify must be able to.
+It governs which of the two is the subject of the sentence.
+
+**Why it is separate from R7**: R7 orders *finding before evidence*. R10 governs *register* — a
+response can lead with its finding and still state that finding in vocabulary only its author
+holds. Both failures leave the reader unable to act; they are different failures.
+
+### Rule 11: Every Option Carries Its Own Trade-off （Optional）
+
+**Trigger**: a response that asks the reader to choose between two or more courses of action.
+
+Rule 2 requires marking the recommended option and giving *its* reason. Rule 11 extends that to
+the rest: **each** option states what it buys and what it costs, in its own terms.
+
+A list of options where only the recommended one is argued hands the comparison back to the
+reader — which is the work they asked to have done. And an option presented without its downside
+reads as having none, which is rarely true and never verifiable from the list alone.
+
+```markdown
+> **Please choose:**
+> | Option | Buys you | Costs you |
+> |---|---|---|
+> | **(A) …** ⭐ **Recommended** — [why this one] | … | … |
+> | **(B) …** | … | … |
+```
+
+**A trade-off is not a hedge.** "This may be slightly harder" is not a cost; "this rewrites 110
+files and needs a human to check the translations" is. If an option genuinely has no downside
+worth stating, say so explicitly rather than leaving the column empty — an empty cell reads as
+"not analysed", and the reader cannot tell those apart.
+
+**Composes with Rule 4**: the option count stays bounded (1–5). Trade-offs make each option
+costlier to read, so this rule makes Rule 4's cap matter more, not less.
+
 ---
 
 ## Contextual Templates
@@ -356,6 +406,8 @@ Each tool's integration layer is responsible for rendering the Navigation Footer
 | R7 | *(Optional)* Lead with the finding; evidence follows the claim it supports |
 | R8 | *(Optional)* 3+ turns or 3+ steps → restate state in one line |
 | R9 | *(Optional)* No preamble. Closers still required — see R1 |
+| R10 | *(Optional)* Plain language is the subject; identifiers support it, after the claim |
+| R11 | *(Optional)* Every option states what it buys and costs — not only the recommended one |
 
 | Exempt | Not Exempt |
 |--------|------------|
@@ -379,6 +431,7 @@ Each tool's integration layer is responsible for rendering the Navigation Footer
 
 | Version | Date | Changes |
 |---------|------|---------|
+| 1.3.0 | 2026-08-17 | Add optional R10–R11. R10 governs register: plain language is the subject of the sentence and identifiers support it — distinct from R7, which orders finding before evidence, because a response can lead with its finding and still state it in vocabulary only its author holds. R11 extends Rule 2 from the recommended option to all of them: a list where only the recommendation is argued hands the comparison back to the reader, and an option shown without its cost reads as having none |
 | 1.2.0 | 2026-08-17 | Add optional R7–R9 governing the answer itself (lead with the finding, restate state, no preamble). Borrowed from `ayghri/i-have-adhd` (MIT), 3 of its 10 rules; the other 7 were dropped as duplicated by R1–R2, in conflict with R1, or covered by estimation-standards. Rules 1–6 could all be satisfied by a response that buries its conclusion — R7–R9 close that |
 | 1.1.0 | 2026-06-10 | Add R6 optional model tier annotation (`〔model: Fast\|Standard\|Capable〕`); vendor-neutral; no forced changes to existing skills |
 | 1.0.0 | 2026-03-25 | Initial release |

package/bundled/locales/zh-CN/CHANGELOG.md

@@ -1,7 +1,7 @@
 ---
 source: ../../CHANGELOG.md
-source_version: 6.6.0
-translation_version: 6.6.0
+source_version: 6.7.1
+translation_version: 6.7.1
 last_synced: 2026-08-17
 status: current
 ---
@@ -17,10 +17,36 @@ status: current
 
 ## [Unreleased]
 
+## [6.7.1] - 2026-08-18
+
+### 修正
+
+- **各语系的速查表内嵌的是英文 skill 描述——每一个语系、每一次都是。** `scripts/generate-usage-docs.mjs` 在语系循环**之外**扫描 skill 一次，且固定读 `skills/`（英文来源），于是三份速查表与功能参考共用同一组描述。修正前实测：**`locales/zh-TW/docs/CHEATSHEET.md` 的 82 则描述与英文版逐字节相同**——而且是 6.7.0 之前那个被剥过的 `[UDS] <标签>` 形式，所以繁体中文读者看到的是**用错语言的过期描述**，而他实际安装的 `SKILL.md` 带着完整的中文触发面。`scanSkills()` 现在接受语系并在**循环内**调用，优先取语系版、缺漏时逐个 skill 回退英文。**修在生成器而不是那 82 行**：手改的速查表下一次编辑必然再度与 `SKILL.md` 分岔。
+- **`code-review-assistant` 与 `checkin-assistant` 的 `disable-model-invocation: true` 已移除。** 那个标志**不遵循任何可陈述的规则**：六个带 `status: reference` 的 skill 中，**有四个（`tdd`、`bdd`、`atdd`、`pr-automation`）从未被禁用**，而它们经历的是同一次 XSPEC-095 生命周期迁移——同一个类别、相反的处置——另外八个被禁用的**连 `status` 都没有**。系统自己早已记下后果：`pr-automation-assistant` 把*「审查的实质内容——请用 `/code-review`」*导向那里，**而那条转介在任何模型自主的路径上都到不了**。六个 reference 现在处置一致，规则因此说得出口：**reference 一律可被模型调用**。两个文件内都就地记录了理由。**其余八个刻意不动**——它们没有 `status`，拿掉等于用另一个没有规则的动作覆盖一个没有规则的状态；它们已在 XSPEC-378 R5 具名，不再是「不知道为什么关着」。
+
+## [6.7.0] - 2026-08-17
+
+### 修正
+
+- **skill 触发面在三层全数复原——55 个 skill × 英文、zh-TW、zh-CN。** 一个 skill 的 `description` 是模型决定要不要调用它时**唯一看得到的东西**。commit `d415937e`（2026-02-10）把其中 17 个改写成 `[UDS] <标签>`，删掉 `Use when:` 与 `Keywords:` 两行、**连中文关键字一起**；相邻 commit 的标题写着 `token optimization`。当时**只有 token 可数**——没有任何东西在量触发面，于是那个取舍看起来是单边的，而它不是。2026-08-14 测量：55 个含 `SKILL.md` 的 skill 中，**27 个有触发条件、27 个有关键字、0 个有排除条件、28 个两者皆无**——而那 28 个正是方法论核心：tdd、bdd、atdd、spec-driven-dev、code-review、commit-standards、checkin、requirement。
+  - **英文来源**：28 个复原，且**全部 55 个补上排除条件**（`Not for:`）。只加触发不加排除，换来的是过度触发；而一个不该响却响的 skill 会被整个关掉，**连带拖走还能用的那些**。15 个可从 git 历史救回者中**有 8 个被重写**，因为历史文字已不描述现行行为——其中六个宣称自己会引导某套生命周期，而那已于 XSPEC-095 移交采用层。**救回一个过期的描述，比不救更糟。**
+  - **语系层**：zh-TW 与 zh-CN **各 55/55，是翻译不是转码**。**这一半才是重点**——以 `--locale zh-tw` 安装的项目，在英文来源已修好时仍拿到被剥过的描述，这个修正本来到不了它要给的那个读者。繁体与简体各自用地道用词，另修正三份 zh-CN 描述中混入的繁体字。
+  - **翻译 drift 62 → 38**，剩下的 38 是刻意的停点：24 份漂移完全来自本次 description 编辑者更新了 hash，12 份正文早已漂移者保留过期 hash——更新它们等于宣称整份文件已同步，而那件事没有人验证过。
+  - ⚠️ **28 个中有 10 个带着 `disable-model-invocation: true`**，由同一个 `d415937e` 加入。对那 10 个而言，补描述**并不会**让它们变成可被选中——挡住的是那个标志，而要不要拿掉它是**设计决定不是缺陷**。模型真正选得到的数量是 **45，不是 55**。
+
+### 新增
+
+- **`ai-response-navigation` 1.2.0 → 1.3.0 —— 可选规则 R10 与 R11。** 它们的来源与 R7–R9 不同：用户在同一次工作会话中**两度**指出，一个正确且完整的回答读不懂，而当时 R7–R9 已经出货且正在被遵守。**先讲发现并不足够。**
+  - **R10 —— 白话是主语，标识符是佐证。** *触发*：任何向人解释一个情况、一个缺陷、或一个系统行为的响应。用读者会用的话说清楚发生了什么；路径、符号、行号、命令输出、版本字符串属于它们所支持的那句话**之后**，而不是那句话本身。它**不是**可以省略它们的许可——想验证的读者必须验得了。**与 R7 分开是刻意的**：R7 管的是「先发现后证据」的顺序，而一个响应可以先讲发现、却仍用只有作者持有的词汇讲它。两者都让读者无法行动，但它们是不同的失效。
+  - **R11 —— 每个选项都要带自己的利弊。** *触发*：要求读者在两个以上做法之间选择的响应。规则 2 已要求标示推荐项并给出**它的**理由；R11 要求**每一个**选项都说明它换到什么、代价是什么。一份只有推荐项被论证的清单，等于**把比较的工作丢回给读者**——而那正是他请你做的事；而没标代价的选项读起来像是没有代价。**利弊不是模棱两可**：「稍微难一点」不是代价，「重写 110 个文件且翻译需要人审」才是。空白的代价栏读起来是「没有分析过」，而读者分不出这两者。
+
 ## [6.6.0] - 2026-08-17
 
 ### 新增
 
+- **`spec-driven-development` 2.3.0 → 2.4.0 —— 没有验证项的 AC 不是 AC。** 每一条验收标准都必须有一个**指向它的验证项**——测试、检查、闸门，或一则明确记录的手动步骤。没有任何验证项引用的 AC 是一张没有人兑现的支票，而且它**不会**大声失败：它只是安静地停止成立，而规格继续宣称它为真。**规则**：这样的 AC 必须**降级为设计意图**，不得继续挂在 AC 栏——降级是诚实的，未经验证的 AC 不是。标准同时写明什么**不算**验证项：「审查者会注意到」不是验证项，因为审查者读的是规格，而规格说那条 AC 成立。新增规则 `SDD-AC-VERIFIED`。
+  - **实测案例**：一份 2026-05-14 的规格写着 `AC-7：旧版系统报告完整保留（无回归）`。它的 Test Plan 有七项，**没有一项指向 AC-7**。该报告的 timer 是 disabled、部署函数从未被调用——**从那条 AC 被写下的同一天起**。三个月后在验证一件无关的安装时偶然撞到。它不是接上了检查后来松脱，**它从来没有被接上过**。
+
 - **`ai-response-navigation` 1.1.0 → 1.2.0 —— 可选规则 R7–R9，管答案本身**（XSPEC 借鉴 B-10，来源 [`ayghri/i-have-adhd`](https://github.com/ayghri/i-have-adhd)，MIT）。规则 1–6 管的是答案**之后**要附什么：导航区块、标记过的推荐、匹配响应类型的模板。**答案本身没有任何规则在管。** 于是一个响应可以把结论埋在一整面证据底下，只要结尾附上正确的导航区块，它仍然满足**本标准的每一条**——而找不到答案的读者，不会因为被告知下一步而得到帮助。
   - **R7 —— 先讲发现，不要先讲过程。** *触发*：回答问题、汇报调查结果、或提出决策的响应。第一行写**查到了什么**或**该做什么**——不是方法、不是把问题复述一遍、不是回答的计划。证据（`file:line`、命令输出、表格、测量数字）是**佐证**，应放在它所支持的论断之后；以证据开场会迫使读者自行重建结论，而那正是他请你做的工作。本条规范的是**顺序**，**不**代表可以省略证据。
   - **R8 —— 每一轮重述进度。** *触发*：跨 3 轮以上的对话，或含 3 个以上步骤的任务。用一行说明工作进行到哪里。不能假设读者能在消息之间记住「我们在 5 步中的第 3 步」，而重述它的成本是一个句子。与模板 4（进行中）互补：**R8 管开头，模板管结尾。**

package/bundled/locales/zh-CN/README.md

@@ -15,7 +15,7 @@ status: current
 
 > **语言**: [English](../../README.md) | [繁體中文](../zh-TW/README.md) | 简体中文
 
-**版本**: 6.6.0 | **发布日期**: 2026-08-17 | **授权**: [双重授权](../../LICENSE) (CC BY 4.0 + MIT)
+**版本**: 6.7.1 | **发布日期**: 2026-08-18 | **授权**: [双重授权](../../LICENSE) (CC BY 4.0 + MIT)
 
 语言无关、框架无关的软件项目文档标准。通过 AI 原生工作流，确保不同技术栈之间的一致性、质量和可维护性。
 

package/bundled/locales/zh-CN/SECURITY.md

@@ -13,7 +13,7 @@ status: current
 <!-- UDS_SUPPORTED_VERSIONS_START -->
 | 版本 | 支持状态 |
 |------|--------|
-| 6.6.0 | ✅ 最新正式版 |
+| 6.7.1 | ✅ 最新正式版 |
 | < 6.0.0 | ❌ 已终止支持 |
 <!-- UDS_SUPPORTED_VERSIONS_END -->
 

package/bundled/locales/zh-CN/core/ai-response-navigation.md

@@ -1,7 +1,7 @@
 ---
 source: ../../../core/ai-response-navigation.md
-source_version: 1.2.0
-translation_version: 1.2.0
+source_version: 1.3.0
+translation_version: 1.3.0
 last_synced: 2026-08-17
 status: current
 ---
@@ -10,7 +10,7 @@ status: current
 
 > **语言**: [English](../../../core/ai-response-navigation.md) | [繁體中文](../../zh-TW/core/ai-response-navigation.md) | 简体中文
 
-**版本**: 1.2.0
+**版本**: 1.3.0
 **最后更新**: 2026-08-17
 **适用范围**: 所有使用 AI 辅助开发的项目
 **范围**: universal
@@ -27,8 +27,9 @@ status: current
 
 **解决方案**：在每个实质性 AI 响应结尾附加标准化的「导航区块」，包含情境模板、推荐标记和弹性选项数量。
 
-**范围注记（v1.2.0）**：规则 1–6 管的是答案**之后**要附什么。规则 7–9 于 1.2.0 新增、属**可选**，
-管的是答案本身：先讲发现、每轮重述进度、不要开场白。新增的理由是——
+**范围注记（v1.2.0，v1.3.0 扩充）**：规则 1–6 管的是答案**之后**要附什么。
+规则 7–11 **全部属可选**，管的是答案本身：先讲发现（R7）、每轮重述进度（R8）、不要开场白（R9）、
+白话是主语（R10）、每个选项都要带自己的利弊而非只有推荐项有（R11）。新增的理由是——
 一个响应可以满足规则 1–6 的每一条，同时把结论埋起来；
 **而找不到答案的读者，不会因为结尾有一个正确的导航区块被告知下一步而得到帮助。**
 
@@ -108,9 +109,11 @@ status: current
 
 ---
 
-## 导航之前的那个答案（规则 7–9，可选）
+## 导航之前的那个答案（规则 7–11，可选）
 
-> **借鉴自**：[`ayghri/i-have-adhd`](https://github.com/ayghri/i-have-adhd)（MIT），十条中取三条。
+> **规则 7–9 借鉴自**：[`ayghri/i-have-adhd`](https://github.com/ayghri/i-have-adhd)（MIT），十条中取三条。
+> **规则 10–11 于 1.3.0 新增**，来源不同——用户在同一次工作会话中两度指出，
+> 一个正确且完整的回答读不懂。当时规则 7–9 已经出货且正在被遵守。
 > 其余七条删去：两条已被上方规则 1–2 涵盖，五条与本标准冲突
 > （它的「不要 recap／不要结语」与规则 1 的导航区块直接矛盾；它的「列表上限 5 项」
 > 会截断证据表格与遍历分母）或与 [estimation-standards](estimation-standards.md) 重复。
@@ -119,7 +122,7 @@ status: current
 一个响应可以把结论埋在一整面证据底下，只要结尾附上正确的导航区块，
 它仍然满足本标准的每一条。**找不到答案的读者，不会因为被告知下一步而得到帮助。**
 
-**这三条是可选的**，语义同规则 6：采用项目不必启用，既有 skill 也不需回头补。
+**这五条是可选的**，语义同规则 6：采用项目不必启用，既有 skill 也不需回头补。
 项目**可以**在自己的配置中把任一条提升为必须。**不可选的是它们必须有精确的触发条件**——
 一条松到永远不会启动的规则，与没有这条规则无从分辨。
 
@@ -161,6 +164,46 @@ status: current
 **规则 9 不适用于结语。** 规则 1 要求的导航区块依然成立——
 响应的结尾正是本标准安放「读者下一步」的位置。
 
+### 规则 10：白话是主语，标识符是佐证（可选）
+
+**触发条件**：任何向人解释一个情况、一个缺陷、或一个系统行为的响应。
+
+用读者会用的话说清楚发生了什么。文件路径、符号名称、行号、命令输出、版本字符串是**佐证**——
+它们属于它们所支持的那句话**之后**，而不是那句话本身。
+
+| 不要写 | 改写成 |
+|---|---|
+| 「`intel-scout.py:883` 的 `load_topics()` 读 `intel-topics.yaml`，`:1033` 的 `load_feeds()` 读 `intel-feeds.yaml`。」 | 「它有两种取材方式：搜关键字，和订阅固定几个博客。」*（然后再附两个调用点）* |
+| 「`manifest.skillHashes` 有 137 条，key 是 `claude-code/project/<n>/SKILL.md`，而查询用的是 `.claude/skills/<n>`。」 | 「哈希值存在一套命名下，查询用的是另一套，所以一个都找不到。」*（然后再贴两边的 key）* |
+
+这**不是**可以省略标识符的许可——想验证的读者必须验得了。它规范的是**两者之中哪一个当主语**。
+
+**为什么它与 R7 是两条**：R7 规范的是**先讲发现再给证据**的顺序。R10 规范的是**语域**——
+一个响应可以先讲发现，却仍然用只有作者持有的词汇讲那个发现。两者都让读者无法行动，但它们是不同的失效。
+
+### 规则 11：每个选项都要带自己的利弊（可选）
+
+**触发条件**：要求读者在两个以上做法之间选择的响应。
+
+规则 2 要求标示推荐选项并给出**它的**理由。规则 11 把这件事扩及其余：
+**每一个**选项都要用它自己的话说明它换到什么、代价是什么。
+
+一份只有推荐项被论证的选项清单，等于**把比较的工作丢回给读者**——而那正是他请你做的事。
+而一个没有标出代价的选项，读起来像是没有代价，这很少为真，且从清单本身无从验证。
+
+```markdown
+> **请选择：**
+> | 选项 | 换到什么 | 代价是什么 |
+> |---|---|---|
+> | **(A) …** ⭐ **推荐** — [为什么是这个] | … | … |
+> | **(B) …** | … | … |
+```
+
+**利弊不是模棱两可。**「这可能会稍微难一点」不是代价；「这要重写 110 个文件，而且翻译需要人审」才是。
+若某个选项真的没有值得一提的代价，**明说**，不要留空——空白读起来是「没有分析过」，而读者分不出这两者。
+
+**与规则 4 相辅**：选项数维持在 1–5。利弊让每个选项读起来更花力气，所以这条规则让规则 4 的上限**更**要紧，不是更不要紧。
+
 ---
 
 ## 情境模板
@@ -353,6 +396,8 @@ AI 需要用户做出选择或提供信息时使用。
 | R7 | *（可选）* 先讲发现；证据放在它所支持的论断之后 |
 | R8 | *（可选）* 跨 3 轮或 3 步以上 → 用一行重述进度 |
 | R9 | *（可选）* 不要开场白。结语仍为必须——见 R1 |
+| R10 | *（可选）* 白话是主语；标识符放在论断之后当佐证 |
+| R11 | *（可选）* 每个选项都要说明换到什么、代价是什么——不只推荐那一个 |
 
 | 豁免 | 不豁免 |
 |------|--------|
@@ -376,6 +421,7 @@ AI 需要用户做出选择或提供信息时使用。
 
 | 版本 | 日期 | 变更 |
 |------|------|------|
+| 1.3.0 | 2026-08-17 | 新增可选规则 R10–R11。R10 管语域:白话是句子的主语、标识符当佐证——与 R7 不同,R7 管的是「先发现后证据」的顺序,而一个响应可以先讲发现却仍用只有作者持有的词汇讲它。R11 把规则 2 从推荐选项扩及全部:只论证推荐项的清单等于把比较丢回给读者,而没标代价的选项读起来像没有代价 |
 | 1.2.0 | 2026-08-17 | 新增可选规则 R7–R9，管答案本身（先讲发现、重述进度、不要开场白）。借鉴自 `ayghri/i-have-adhd`（MIT），十条取三；其余七条因已被 R1–R2 涵盖、与 R1 冲突、或与 estimation-standards 重复而删去。规则 1–6 全部可以被一个把结论埋起来的响应满足——R7–R9 补上这个缺口 |
 | 1.1.0 | 2026-06-10 | 新增规则 R6 可选模型级别标注（`〔模型：Fast｜Standard｜Capable〕`）；与厂商无关；不强制既有技能回改 |
 | 1.0.0 | 2026-03-25 | 初始版本 |

package/bundled/locales/zh-CN/docs/CHEATSHEET.md

@@ -1,6 +1,6 @@
 # UDS 速查表
 
-> Quick reference for all UDS features | Last updated: 2026-08-12
+> Quick reference for all UDS features | Last updated: 2026-08-17
 
 **Language**: [English](../../../docs/user/CHEATSHEET.md) | [繁體中文](../../zh-TW/docs/CHEATSHEET.md) | 简体中文
 
@@ -80,61 +80,61 @@
 
 | Skill | 说明 |
 |-------|-------------|
-| `ac-coverage` | "[UDS] Analyze AC-to-test traceability and coverage" |
-| `adr-assistant` | [UDS] Create, manage, and track Architecture Decision Record |
-| `ai-collaboration-standards` | Prevent AI hallucination and ensure evidence-based responses |
-| `ai-friendly-architecture` | Design AI-friendly architecture with explicit patterns, laye |
-| `ai-instruction-standards` | Create and maintain AI instruction files (CLAUDE.md, AGENTS. |
-| `api-design-assistant` | Guide API design following REST, GraphQL, and gRPC best prac |
-| `atdd-assistant` | "[UDS] Guide through Acceptance Test-Driven Development work |
-| `audit-assistant` | "[UDS] UDS Health & Feedback System" |
-| `bdd-assistant` | "[UDS] Guide through Behavior-Driven Development workflow" |
-| `brainstorm-assistant` | "[UDS] Structured AI-assisted brainstorming before spec crea |
-| `changelog-guide` | "[UDS] Generate and maintain CHANGELOG.md entries" |
-| `checkin-assistant` | "[UDS] Pre-commit quality gates verification" |
-| `ci-cd-assistant` | Guide CI/CD pipeline design, configuration, and optimization |
-| `code-review-assistant` | "[UDS] Perform systematic code review with checklist" |
-| `commit-standards` | "[UDS] Generate commit messages following Conventional Commi |
-| `contract-test-assistant` | [UDS] Guide contract testing strategy for APIs and microserv |
-| `database-assistant` | Guide database design, migration, and query optimization. |
-| `deploy-assistant` | Guide reliable deployments without CI/CD platforms (GitHub A |
-| `dev-methodology` | "[UDS] Manage development methodology workflow" |
-| `dev-workflow-guide` | "[UDS] Guide for mapping software development phases to UDS  |
-| `docs-generator` | "[UDS] Generate usage documentation from project sources" |
-| `documentation-guide` | Guide documentation structure, content requirements, and pro |
-| `durable-execution-assistant` | "[UDS] Guide workflow failure recovery with checkpoints, ret |
-| `e2e-assistant` | "[UDS] Generate E2E test skeletons from BDD scenarios" |
-| `error-code-guide` | Design consistent error codes following the PREFIX_CATEGORY_ |
-| `git-workflow-guide` | Guide Git branching strategies, branch naming, and merge ope |
-| `incident-response-assistant` | Guide incident response, root cause analysis, and post-morte |
-| `journey-test-assistant` | "[UDS] Generate coherent user journey test plans (TESTPLAN)  |
-| `knowledge-graph` | "[UDS] Trace spec/decision/code impact chains via a knowledg |
-| `logging-guide` | Implement structured logging with proper log levels and sens |
-| `metrics-dashboard-assistant` | "[UDS] Track development metrics, code quality indicators, a |
-| `migration-assistant` | "[UDS] Guide code migration, framework upgrades, and technol |
-| `observability-assistant` | Guide observability setup, metrics design, and alerting conf |
-| `orchestrate` | Orchestrate multi-task execution plans using Claude's native |
-| `plan` | Generate plan.json from Spec documents, OpenSpec changes, or |
-| `pr-automation-assistant` | Guide pull request creation, review automation, and merge st |
-| `project-discovery` | "[UDS] Assess project health, architecture, and risks before |
-| `project-structure-guide` | Guide for organizing project directories following language- |
-| `push` | AI-assisted safety layer for git push operations with qualit |
-| `refactoring-assistant` | "[UDS] Guide refactoring decisions and strategy selection" |
-| `release-standards` | "[UDS] Guide release process and changelogs" |
-| `requirement-assistant` | "[UDS] Write user stories and requirements following INVEST  |
-| `retrospective-assistant` | [UDS] Guide structured team retrospectives for Sprint and Re |
-| `reverse-engineer` | "[UDS] System archeology - reverse engineer code across Logi |
-| `runbook-assistant` | Guide runbook creation, maintenance, and drill exercises. |
-| `security-assistant` | Guide security review and vulnerability assessment following |
-| `security-scan-assistant` | Guide automated security scanning, dependency auditing, and  |
-| `skill-builder` | "[UDS] Identify repeated processes and build Skills with the |
-| `slo-assistant` | Guide SLI selection, SLO setting, and Error Budget managemen |
-| `spec-derivation` | "[UDS] Derive BDD scenarios, TDD skeletons, or ATDD tables f |
-| `spec-driven-dev` | "[UDS] Create or review specification documents for Spec-Dri |
-| `sweep` | Scan codebase for debug artifacts and code quality issues; o |
-| `tdd-assistant` | "[UDS] Guide through Test-Driven Development workflow" |
-| `test-coverage-assistant` | "[UDS] Analyze test coverage and provide recommendations" |
-| `testing-guide` | Testing pyramid and test writing standards for UT/IT/ST/E2E. |
+| `ac-coverage` | [UDS] 分析验收条件（AC）与测试之间的追踪关系，并生成需求层级的覆盖率报告。 |
+| `adr-assistant` | [UDS] 创建、管理并追踪架构决策记录（ADR）。 |
+| `ai-collaboration-standards` | 防止 AI 幻觉，确保分析代码或提出建议时给出以证据为基础的回应。 |
+| `ai-friendly-architecture` | 设计 AI 友善架构，包含明确的模式、分层文档与语义边界。 |
+| `ai-instruction-standards` | 创建并维护 AI 指令文件（CLAUDE.md、AGENTS.md、.cursor/rules/ 等），并采用适当结构。 |
+| `api-design-assistant` | 引导 API 设计，遵循 REST、GraphQL 与 gRPC 最佳实践。 |
+| `atdd-assistant` | [UDS] 验收测试驱动开发（ATDD）的参考资料：INVEST 准则、Gherkin 验收条件格式与 Three Am |
+| `audit-assistant` | [UDS] 诊断 UDS 安装的健康状态，并向上游提交结构化反馈。 |
+| `bdd-assistant` | [UDS] 行为驱动开发（BDD）的参考资料：Gherkin 的 Given-When-Then 格式与 Three A |
+| `brainstorm-assistant` | [UDS] 在规格出现之前执行的结构化多角色头脑风暴，并附带评分质量关卡。 |
+| `changelog-guide` | [UDS] 以 Keep a Changelog 格式生成并维护 CHANGELOG.md 条目。 |
+| `checkin-assistant` | [UDS] 提交前质量关卡的参考资料：关卡定义、检查清单项目，以及绝不可提交的规则。 |
+| `ci-cd-assistant` | 引导 CI/CD 流水线的设计、配置与优化。 |
+| `code-review-assistant` | [UDS] 系统性代码审查的参考资料：八大审查类别，以及 BLOCKING/IMPORTANT/SUGGESTION 评 |
+| `commit-standards` | [UDS] 生成符合 Conventional Commits 规范的 commit message，包含双语格式。 |
+| `contract-test-assistant` | [UDS] 引导 API 与微服务的契约测试策略。 |
+| `database-assistant` | 引导数据库设计、迁移与查询优化。 |
+| `deploy-assistant` | 引导在没有 CI/CD 平台（GitHub Actions／GitLab CI）的情况下完成可靠部署。 |
+| `dev-methodology` | [UDS] 为项目选择并追踪当前采用的开发方法论（SDD、BDD、TDD）。 |
+| `dev-workflow-guide` | [UDS] 把目前的软件开发阶段对应到正确的 UDS 命令与 Skill。 |
+| `docs-generator` | [UDS] 从项目源文件生成使用文档（速查表、参考手册、使用指南）。 |
+| `documentation-guide` | 引导文档结构、内容需求与项目文档的最佳实践。 |
+| `durable-execution-assistant` | [UDS] 引导容错工作流设计，包含检查点、重试策略与回滚计划。 |
+| `e2e-assistant` | [UDS] 从 BDD 的 .feature 场景生成 E2E 测试骨架，并支持框架检测与覆盖缺口分析。 |
+| `error-code-guide` | 设计一致的错误码，遵循 PREFIX_CATEGORY_NUMBER 格式。 |
+| `git-workflow-guide` | 引导 Git 分支策略、分支命名与合并操作。 |
+| `incident-response-assistant` | 引导事故响应、根因分析与事后复盘文档撰写。 |
+| `journey-test-assistant` | [UDS] 从项目描述生成连贯的用户旅程测试计划（TESTPLAN）与旅程 E2E 骨架。 |
+| `knowledge-graph` | [UDS] 通过知识图谱追踪规格、决策与代码之间的影响链；没有引擎时以 Markdown 后备方案运作。 |
+| `logging-guide` | 实现结构化日志，包含适当的日志级别与敏感数据处理。 |
+| `metrics-dashboard-assistant` | [UDS] 长期追踪开发指标、代码质量指标与技术债。 |
+| `migration-assistant` | [UDS] 引导系统性的代码迁移、框架升级与技术现代化。 |
+| `observability-assistant` | 引导可观测性建设、指标设计与告警配置。 |
+| `orchestrate` | 以 Claude 原生 Agent tool 编排多任务执行计划（以 DAG 为基础，不需外部引擎）。 |
+| `plan` | 从 Spec 文档、OpenSpec 变更或自由文本需求生成 plan.json。 |
+| `pr-automation-assistant` | 引导 pull request 创建、审查自动化与合并策略。 |
+| `project-discovery` | [UDS] 在既有代码库新增功能之前，评估项目健康度、架构与风险。 |
+| `project-structure-guide` | 依各语言的最佳实践组织项目目录结构的指南。 |
+| `push` | AI 辅助的 git push 安全层，提供质量关卡与协作护栏。 |
+| `refactoring-assistant` | [UDS] 引导重构决策与策略选择，包含「重构还是重写」这个判断。 |
+| `release-standards` | [UDS] 引导发布流程——语义化版本、发布模式，以及 start/finish/promote/deploy 的顺序。 |
+| `requirement-assistant` | [UDS] 撰写符合 INVEST 准则的用户故事与需求。 |
+| `retrospective-assistant` | [UDS] 引导 Sprint 与 Release 周期的结构化团队回顾。 |
+| `reverse-engineer` | [UDS] 系统考古——从逻辑、数据、运行时三个维度对既有系统做逆向工程。 |
+| `runbook-assistant` | 引导 Runbook 的撰写、维护与演练。 |
+| `security-assistant` | 引导安全审查与漏洞评估，遵循 OWASP 标准。 |
+| `security-scan-assistant` | 引导自动化安全扫描、依赖包审计与密钥检测。 |
+| `skill-builder` | [UDS] 把重复的手动流程转成范围界定得宜的 Skill，过程中拿捏恰当的流程分量。 |
+| `slo-assistant` | 引导 SLI 选取、SLO 设置与 Error Budget 管理。 |
+| `spec-derivation` | [UDS] 从已批准的规格推导出 BDD 场景、TDD 骨架、集成与 E2E 测试，以及 ATDD 表格。 |
+| `spec-driven-dev` | [UDS] 在写代码之前建立并审查规格文档——规格格式、状态与差异操作。 |
+| `sweep` | 扫描代码库中的调试残留与代码质量问题；可选择自动修正安全的模式。 |
+| `tdd-assistant` | [UDS] 测试驱动开发（TDD）的参考资料：红-绿-重构循环、FIRST 原则与 Arrange-Act-Assert |
+| `test-coverage-assistant` | [UDS] 以八维度框架分析代码层级的测试覆盖率，并建议该优先补上哪些缺口。 |
+| `testing-guide` | 测试金字塔，以及 UT/IT/ST/E2E 的测试编写标准。 |
 
 ## 🤖 代理