universal-dev-standards 5.15.1 → 5.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (80) hide show
  1. package/bundled/ai/standards/acceptance-criteria-traceability.ai.yaml +31 -0
  2. package/bundled/ai/standards/forward-derivation-standards.ai.yaml +23 -0
  3. package/bundled/ai/standards/knowledge-graph-memory.ai.yaml +1 -1
  4. package/bundled/core/acceptance-criteria-traceability.md +46 -0
  5. package/bundled/core/forward-derivation-standards.md +19 -0
  6. package/bundled/core/knowledge-graph-memory.md +2 -2
  7. package/bundled/locales/zh-CN/CHANGELOG.md +13 -3
  8. package/bundled/locales/zh-CN/README.md +1 -1
  9. package/bundled/locales/zh-CN/core/acceptance-criteria-traceability.md +46 -0
  10. package/bundled/locales/zh-CN/core/forward-derivation-standards.md +19 -0
  11. package/bundled/locales/zh-CN/skills/ac-coverage/SKILL.md +194 -0
  12. package/bundled/locales/zh-CN/skills/adr-assistant/SKILL.md +135 -40
  13. package/bundled/locales/zh-CN/skills/brainstorm-assistant/SKILL.md +217 -63
  14. package/bundled/locales/zh-CN/skills/brainstorm-assistant/guide.md +599 -0
  15. package/bundled/locales/zh-CN/skills/commands/brainstorm.md +92 -25
  16. package/bundled/locales/zh-CN/skills/commit-standards/SKILL.md +78 -16
  17. package/bundled/locales/zh-CN/skills/contract-test-assistant/SKILL.md +85 -26
  18. package/bundled/locales/zh-CN/skills/deploy-assistant/SKILL.md +189 -0
  19. package/bundled/locales/zh-CN/skills/dev-methodology/SKILL.md +110 -0
  20. package/bundled/locales/zh-CN/skills/dev-methodology/guide.md +255 -0
  21. package/bundled/locales/zh-CN/skills/dev-workflow-guide/SKILL.md +70 -11
  22. package/bundled/locales/zh-CN/skills/journey-test-assistant/SKILL.md +209 -0
  23. package/bundled/locales/zh-CN/skills/knowledge-graph/SKILL.md +58 -0
  24. package/bundled/locales/zh-CN/skills/knowledge-graph/guide.md +74 -0
  25. package/bundled/locales/zh-CN/skills/migration-assistant/SKILL.md +125 -8
  26. package/bundled/locales/zh-CN/skills/observability-assistant/guide.md +188 -0
  27. package/bundled/locales/zh-CN/skills/orchestrate/SKILL.md +173 -0
  28. package/bundled/locales/zh-CN/skills/plan/SKILL.md +240 -0
  29. package/bundled/locales/zh-CN/skills/push/SKILL.md +242 -0
  30. package/bundled/locales/zh-CN/skills/retrospective-assistant/SKILL.md +104 -36
  31. package/bundled/locales/zh-CN/skills/reverse-engineer/SKILL.md +88 -32
  32. package/bundled/locales/zh-CN/skills/runbook-assistant/guide.md +216 -0
  33. package/bundled/locales/zh-CN/skills/skill-builder/SKILL.md +149 -0
  34. package/bundled/locales/zh-CN/skills/slo-assistant/guide.md +188 -0
  35. package/bundled/locales/zh-CN/skills/spec-derivation/SKILL.md +86 -0
  36. package/bundled/locales/zh-CN/skills/spec-derivation/guide.md +476 -0
  37. package/bundled/locales/zh-CN/skills/spec-driven-dev/SKILL.md +155 -81
  38. package/bundled/locales/zh-CN/skills/sweep/SKILL.md +151 -0
  39. package/bundled/locales/zh-CN/skills/testing-guide/SKILL.md +207 -110
  40. package/bundled/locales/zh-TW/CHANGELOG.md +13 -3
  41. package/bundled/locales/zh-TW/README.md +1 -1
  42. package/bundled/locales/zh-TW/core/acceptance-criteria-traceability.md +46 -0
  43. package/bundled/locales/zh-TW/core/browser-compatibility-standards.md +222 -5
  44. package/bundled/locales/zh-TW/core/contract-testing-standards.md +184 -5
  45. package/bundled/locales/zh-TW/core/cross-flow-regression.md +192 -5
  46. package/bundled/locales/zh-TW/core/forward-derivation-standards.md +19 -0
  47. package/bundled/locales/zh-TW/core/knowledge-graph-memory.md +2 -2
  48. package/bundled/locales/zh-TW/core/release-readiness-gate.md +186 -5
  49. package/bundled/locales/zh-TW/skills/adr-assistant/SKILL.md +21 -42
  50. package/bundled/locales/zh-TW/skills/brainstorm-assistant/SKILL.md +212 -59
  51. package/bundled/locales/zh-TW/skills/brainstorm-assistant/guide.md +266 -579
  52. package/bundled/locales/zh-TW/skills/commands/brainstorm.md +91 -26
  53. package/bundled/locales/zh-TW/skills/commit-standards/SKILL.md +77 -15
  54. package/bundled/locales/zh-TW/skills/contract-test-assistant/SKILL.md +75 -16
  55. package/bundled/locales/zh-TW/skills/dev-methodology/guide.md +255 -0
  56. package/bundled/locales/zh-TW/skills/dev-workflow-guide/SKILL.md +125 -64
  57. package/bundled/locales/zh-TW/skills/knowledge-graph/SKILL.md +5 -5
  58. package/bundled/locales/zh-TW/skills/knowledge-graph/guide.md +74 -0
  59. package/bundled/locales/zh-TW/skills/migration-assistant/SKILL.md +128 -11
  60. package/bundled/locales/zh-TW/skills/observability-assistant/guide.md +188 -0
  61. package/bundled/locales/zh-TW/skills/orchestrate/SKILL.md +3 -2
  62. package/bundled/locales/zh-TW/skills/plan/SKILL.md +3 -2
  63. package/bundled/locales/zh-TW/skills/push/SKILL.md +3 -2
  64. package/bundled/locales/zh-TW/skills/retrospective-assistant/SKILL.md +94 -28
  65. package/bundled/locales/zh-TW/skills/reverse-engineer/SKILL.md +84 -28
  66. package/bundled/locales/zh-TW/skills/runbook-assistant/guide.md +216 -0
  67. package/bundled/locales/zh-TW/skills/slo-assistant/guide.md +188 -0
  68. package/bundled/locales/zh-TW/skills/spec-derivation/guide.md +476 -0
  69. package/bundled/locales/zh-TW/skills/spec-driven-dev/SKILL.md +148 -77
  70. package/bundled/locales/zh-TW/skills/testing-guide/SKILL.md +141 -44
  71. package/bundled/skills/brainstorm-assistant/SKILL.md +142 -106
  72. package/bundled/skills/brainstorm-assistant/guide.md +256 -661
  73. package/bundled/skills/commands/brainstorm.md +51 -30
  74. package/bundled/skills/knowledge-graph/SKILL.md +5 -5
  75. package/bundled/skills/knowledge-graph/guide.md +4 -4
  76. package/package.json +2 -2
  77. package/src/commands/check.js +11 -2
  78. package/src/lint/i18n.js +109 -23
  79. package/standards-registry.json +4 -4
  80. package/bundled/locales/zh-TW/docs/SKILL-FALLBACK-GUIDE.md +0 -407
@@ -1,11 +1,192 @@
1
1
  ---
2
2
  source: ../../../core/release-readiness-gate.md
3
3
  source_version: 1.0.0
4
- translation_version: 0.0.0
5
- last_synced: 2026-05-05
4
+ translation_version: 1.0.0
5
+ last_synced: 2026-06-02
6
+ source_hash: 3d156e19680e
6
7
  ---
7
8
 
8
- <!-- TODO: 待完整繁體中文翻譯 — Translation pending -->
9
- <!-- See source: core/release-readiness-gate.md -->
9
+ # 發布就緒閘門(Release Readiness Gate)
10
10
 
11
- > 此標準尚未完整翻譯。請參閱英文原文:[English](../../../core/release-readiness-gate.md)
11
+ > **語言**:[English](../../../core/release-readiness-gate.md) | 繁體中文
12
+
13
+ **版本**:1.0.0
14
+ **最後更新**:2026-05-05
15
+ **適用範圍**:所有準備進行生產環境發布的軟體專案
16
+ **Scope**:universal
17
+ **業界標準**:ISO/IEC 25010(產品品質)、ISTQB Advanced Test Manager
18
+ **參考文件**:`core/release-quality-manifest.md`、`core/flow-based-testing.md`
19
+
20
+ ---
21
+
22
+ ## 目的
23
+
24
+ 本標準定義一個**單一、彙整式的發布就緒閘門(Release Readiness Gate)**,將所有品質維度統一成生產部署前一個明確的 go/no-go 決策。
25
+
26
+ 若沒有這個閘門,品質證據會散落在 16 個以上的獨立標準中。團隊雖然通過了個別檢查,卻在未驗證某些維度的情況下出貨,因為沒有任何一份文件明說「你必須在發布前通過*所有這些項目*」。
27
+
28
+ 發布就緒閘門:
29
+ - **彙整(Aggregates)** 16 個品質維度成為一份分級 checklist
30
+ - **連結(Connects)** 人工 sign-off(本文件)與機器可讀的證據(`release-quality-manifest.md`)
31
+ - **區分(Distinguishes)** 阻擋性條件與建議性警告
32
+ - **可伸縮(Scales)** 透過 Tier-1 / Tier-2 / Tier-3 分級,以適應不同類型與風險等級的專案
33
+
34
+ ---
35
+
36
+ ## 與發布品質清單(Release Quality Manifest, RQM)的關係
37
+
38
+ | 產物 | 格式 | 對象 | 目的 |
39
+ |----------|--------|----------|---------|
40
+ | **發布就緒 Sign-off**(本文件的範本) | Markdown checklist | 人類(PM、QA、Eng Lead、Business) | Go/no-go 決策、責任歸屬、稽核軌跡 |
41
+ | **發布品質清單**(`release-quality-manifest.md`) | YAML/JSON | CI、工具、客戶 | 機器可讀的彙整、自動化閘門強制執行 |
42
+
43
+ 這兩份產物在每次發布時**並行(in parallel)**產生。Sign-off 涵蓋人工驗證的維度;RQM 涵蓋自動化的維度。兩者在生產部署前都必須為 `PASS` / `WARN`(絕不可為 `FAIL`)。
44
+
45
+ ---
46
+
47
+ ## Tier 分級
48
+
49
+ | Tier | 要求 | 未達標 = ? | 適用對象 |
50
+ |------|-------------|---------|-------------|
51
+ | **Tier-1** | 必須通過;若 `FAIL` 則阻擋發布 | 硬性阻擋(Hard block) | 所有專案 |
52
+ | **Tier-2** | 應通過;`WARN` 須記錄理由;不阻擋 | 記錄在案的 WARN | 所有專案 |
53
+ | **Tier-3** | 當功能集或領域需要時才適用;`N/A` 為有效狀態 | 接受 N/A | 取決於專案類型 |
54
+
55
+ ---
56
+
57
+ ## 16 維度發布就緒矩陣
58
+
59
+ | # | 維度 | Tier | 閘門類型 | 阻擋條件 | 證據 | 標準 | 負責人 |
60
+ |---|-----------|------|-----------|-------------------|----------|---------|-------------|
61
+ | 1 | **效能 / 負載(Performance / Load)** | 2 | 自動化 | p95 latency 退化 > 10%;headroom < 20% | 負載測試報告 | `performance-standards.md` | Eng Lead + SRE |
62
+ | 2 | **安全性(Security)**(SAST/DAST/SCA/secrets) | 1 | 自動化 | 任何 Critical/High CVE、SAST High 未修、diff 中含 secret | SARIF、Trivy、SBOM | `pipeline-security-gates.md` | SecEng / Eng Lead |
63
+ | 3 | **無障礙(Accessibility, a11y)** | 2 | 自動化 + 人工 | axe-core critical > 0;鍵盤導覽路徑中斷 | axe 報告、screen reader 紀錄 | `accessibility-standards.md` §Release-Blocking Threshold | QA + UX |
64
+ | 4 | **API / 合約測試(Contract Testing)** | 3 | 自動化 | 上游 consumer contract 為紅;N-1 相容性中斷 | Pact broker 報告 | `contract-testing-standards.md` | API owner |
65
+ | 5 | **資料庫遷移(Database Migration)** | 1 | 自動化 | up/rollback/idempotency 測試失敗;資料保存測試失敗 | `data-migration-testing.md` 閘門結果 | `data-migration-testing.md` | DB Lead |
66
+ | 6 | **跨流程回歸(Cross-flow Regression)** | 2 | 自動化 | 關鍵 user journey 通過率 < 95%;business-critical flow 組合失敗 | 跨流程回歸報告 | `cross-flow-regression.md` | QA Lead |
67
+ | 7 | **營運就緒(Operational Readiness)** | 1 | 人工 | 缺少 Runbook;alerting 未設定;無 rollback 程序 | Runbook 連結、alert rule 審查 | `runbook-standards.md`、`alerting-standards.md` | SRE / Ops |
68
+ | 8 | **在地化 / i18n(Localization)** | 2 | 自動化 | 發布中有 MISSING 或 MAJOR i18n 落差(semver 落差) | `check-translation-sync.sh` 輸出 | `translation-lifecycle-standards.md` | i18n Lead |
69
+ | 9 | **瀏覽器 / 裝置相容性(Browser / Device Compatibility)** | 3 | 自動化 | Tier-1 瀏覽器/裝置通過率 < 100% | Playwright matrix 報告 | `browser-compatibility-standards.md` | Frontend QA |
70
+ | 10 | **容量 Sign-off(Capacity Sign-off)** | 3 | 人工 | 預估尖峰時 headroom < 30%;無 Eng+SRE sign-off | 容量預測 + sign-off | `performance-standards.md` §Per-Release Capacity Sign-off | SRE + Eng Lead |
71
+ | 11 | **合規 / 隱私(Compliance / Privacy)** | 3 | 人工 | GDPR/CCPA 違規;缺少 audit log;保存政策中斷 | 隱私審查 checklist | `privacy-standards.md` | DPO / Legal |
72
+ | 12 | **文件完整性(Documentation Completeness)** | 2 | 人工 | 此次發布缺少 CHANGELOG;面向客戶的文件未更新 | CHANGELOG diff、文件審查 | `changelog-standards.md`、`documentation-lifecycle.md` | Tech Writer / PM |
73
+ | 13 | **回滾 / 災難復原(Rollback / Disaster Recovery)** | 1 | 人工 | 此次發布無經測試的 rollback 程序;RTO > 門檻 | DR 演練紀錄;rollback script | `rollback-standards.md`、`disaster-recovery-drill.md` | SRE |
74
+ | 14 | **生產 Smoke / Canary(Production Smoke / Canary)** | 1 | 自動化 | 部署後 smoke 失敗;canary error rate > SLO | Smoke 測試結果;canary 儀表板 | `smoke-test.md`、`cd-deployment-strategies.md` | SRE / DevOps |
75
+ | 15 | **Feature Flag 治理(Feature Flag Governance)** | 2 | 人工 | 預設狀態未審查;kill-switch 未測試 | Flag 稽核 checklist | `feature-flag-standards.md` | PM + Eng Lead |
76
+ | 16 | **多閘門流程驗證(Multi-Gate Flow Verification)** | 2 | 自動化 + 人工 | 任何 ≥ 3 步驟的流程缺少 Gate 0;Gate 3 CI 失敗;缺少 Gate 4 UAT sign-off | `flow_gate_report.json`;UAT sign-off 表 | `flow-based-testing.md` §Multi-Gate | QA Lead + Business |
77
+
78
+ > **關於 Tier-3 的說明**:不適用時標記為 `N/A`(例如:CLI 工具的瀏覽器 matrix;無 API consumer 的獨立服務的合約測試)。`N/A` 在 sign-off 中需附上理由註解。
79
+
80
+ ---
81
+
82
+ ## 發布就緒 Sign-off 範本
83
+
84
+ > 每次發布時複製此範本。在 repo 根目錄存為 `.release-readiness/<version>.md`,或附加於發布產物上。
85
+
86
+ ```markdown
87
+ # Release Readiness Sign-off
88
+
89
+ **Release**: [tag/version]
90
+ **Date**: [YYYY-MM-DD]
91
+ **Environment**: Pre-Production → Production
92
+ **RQM Artifact**: [link or commit SHA]
93
+
94
+ ## Tier-1 Gates (ALL must be PASS)
95
+
96
+ | # | Dimension | Status | Evidence | Sign-off |
97
+ |---|-----------|--------|----------|---------|
98
+ | 2 | Security (SAST/DAST/SCA) | PASS / FAIL | [link] | [name] |
99
+ | 5 | Database Migration | PASS / FAIL | [link] | [name] |
100
+ | 7 | Operational Readiness | PASS / FAIL | [link] | [name] |
101
+ | 13 | Rollback / DR | PASS / FAIL | [link] | [name] |
102
+ | 14 | Production Smoke/Canary | PASS / FAIL | [link] | [name] |
103
+
104
+ ## Tier-2 Gates (WARN must have rationale)
105
+
106
+ | # | Dimension | Status | Evidence | Rationale (if WARN) | Sign-off |
107
+ |---|-----------|--------|----------|---------------------|---------|
108
+ | 1 | Performance / Load | PASS / WARN / FAIL | [link] | | [name] |
109
+ | 3 | Accessibility | PASS / WARN / FAIL | [link] | | [name] |
110
+ | 6 | Cross-flow Regression | PASS / WARN / FAIL | [link] | | [name] |
111
+ | 8 | Localization / i18n | PASS / WARN / FAIL | [link] | | [name] |
112
+ | 12 | Documentation | PASS / WARN / FAIL | [link] | | [name] |
113
+ | 15 | Feature Flag Governance | PASS / WARN / FAIL | [link] | | [name] |
114
+ | 16 | Multi-Gate Flow Verification | PASS / WARN / FAIL | [link] | | [name] |
115
+
116
+ ## Tier-3 Gates (N/A with rationale allowed)
117
+
118
+ | # | Dimension | Status | Evidence | Rationale (if N/A) | Sign-off |
119
+ |---|-----------|--------|----------|---------------------|---------|
120
+ | 4 | API / Contract Testing | PASS / WARN / N/A | [link] | | [name] |
121
+ | 9 | Browser / Device Compat | PASS / WARN / N/A | [link] | | [name] |
122
+ | 10 | Capacity Sign-off | PASS / WARN / N/A | [link] | | [name] |
123
+ | 11 | Compliance / Privacy | PASS / WARN / N/A | [link] | | [name] |
124
+
125
+ ## Overall Decision
126
+
127
+ - [ ] **GO** — All Tier-1 PASS; all WARN documented; all N/A have rationale
128
+ - [ ] **NO-GO** — One or more Tier-1 FAIL, or undocumented WARN
129
+
130
+ **Decision made by**: [name, role]
131
+ **Date**: [YYYY-MM-DD]
132
+ ```
133
+
134
+ ---
135
+
136
+ ## 狀態語意(Status Semantics)
137
+
138
+ | 狀態 | 意義 | 對發布的影響 |
139
+ |--------|---------|----------------|
140
+ | `PASS` | 符合或超越所有條件 | 無 |
141
+ | `WARN` | 低於目標但高於硬性最低標;已記錄理由 | 允許;記錄在案 |
142
+ | `FAIL` | 低於硬性最低標;尚未解決 | **阻擋發布** |
143
+ | `N/A` | 此維度不適用於本專案/本次發布;已記錄理由 | 允許 |
144
+
145
+ ---
146
+
147
+ ## 何時建立 Sign-off
148
+
149
+ | 里程碑 | 動作 |
150
+ |-----------|--------|
151
+ | Release candidate 已 tag | 依範本建立 `.release-readiness/<version>.md`;填入證據連結 |
152
+ | Pre-UAT 部署 | 填入 Gate 3 CI 結果;驗證 Tier-1 自動化閘門 |
153
+ | UAT sign-off(Gate 4) | 完成 Tier-3 人工閘門;定案 Multi-Gate Flow 列 |
154
+ | 生產部署決策 | 由 release owner 簽署整體 GO/NO-GO 決策 |
155
+
156
+ Sign-off **不是**事後補做的——Gate 0(PRD 完整性)與 Gate 1(PR 層級測試)必須在 sign-off 文件建立之前很久就已滿足。Sign-off 彙整的是整個發布週期中持續蒐集的證據。
157
+
158
+ ---
159
+
160
+ ## 反模式(Anti-Patterns)
161
+
162
+ - **在部署當天才建立 sign-off** — 證據應在整個發布週期中漸進蒐集
163
+ - **未附理由就標記 WARN** — 沒有記錄理由的 WARN,在功能上等同於無視該閘門
164
+ - **完全略過 Tier-3 而未附 N/A 理由** — 若 web app 省略瀏覽器測試,必須明確說明理由
165
+ - **把 Sign-off 當成橡皮圖章** — 每一列都需要一位具名的 sign-off 負責人;匿名的集體所有權代表沒有真正的責任歸屬
166
+ - **多個發布共用一份 sign-off** — 每個發布 tag 一份 sign-off;不可跨版本重複使用
167
+
168
+ ---
169
+
170
+ ## 另請參閱(See Also)
171
+
172
+ - `release-quality-manifest.md` — 機器可讀的 RQM(本 sign-off 的自動化對應物)
173
+ - `flow-based-testing.md` — Multi-Gate Flow Model(維度 16)
174
+ - `branch-completion.md` — 分支層級閘門(前置條件;不等同於發布就緒)
175
+ - `verification-evidence.md` — 證據標準(所有證據連結都必須符合此標準)
176
+ - `deployment-standards.md` — 部署後閘門整合
177
+
178
+ ---
179
+
180
+ ## 版本歷史(Version History)
181
+
182
+ | 版本 | 日期 | 變更 |
183
+ |---------|------|---------|
184
+ | 1.0.0 | 2026-05-05 | 首次發布:16 維度矩陣、分級 sign-off 範本、RQM 整合 |
185
+
186
+ ---
187
+
188
+ ## 授權(License)
189
+
190
+ 本標準以 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授權發布。
191
+
192
+ **來源(Source)**:[universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)
@@ -2,8 +2,9 @@
2
2
  name: adr-assistant
3
3
  source: ../../../../skills/adr-assistant/SKILL.md
4
4
  source_version: 1.0.0
5
+ source_hash: 7d8bf5944cf4
5
6
  translation_version: 1.0.0
6
- last_synced: 2026-03-26
7
+ last_synced: 2026-06-01
7
8
  status: current
8
9
  description: "[UDS] 建立、管理和追蹤架構決策記錄(ADR)"
9
10
  ---
@@ -148,50 +149,28 @@ docs/adr/
148
149
  > - 更新相關規格以引用此 ADR
149
150
  > - 若狀態為 `Proposed`,分享給團隊審查
150
151
 
151
- ## 參考
152
-
153
- - 核心規範:[adr-standards.md](../../../../core/adr-standards.md)
154
- - 詳細指南:[guide.md](./guide.md)
155
-
156
-
157
- ## Next Steps Guidance | 下一步引導
158
-
159
- After `/adr` completes, the AI assistant should suggest:
160
-
161
- > **ADR created. Suggested next steps:**
162
- > - Execute `/sdd` to create a spec if the decision requires implementation
163
- > - Execute `/commit` to commit the ADR file
164
- > - Update related SPECs to reference this ADR
165
- > - Share with team for review if status is `Proposed`
166
-
167
- > **ADR 已建立。建議下一步:**
168
- > - 執行 `/sdd` 建立規格(若決策需要實作)
169
- > - 執行 `/commit` 提交 ADR 檔案
170
- > - 更新相關規格以引用此 ADR
171
- > - 若狀態為 `Proposed`,分享給團隊審查
152
+ ## AI 代理行為
172
153
 
173
- ## AI Agent Behavior | AI 代理行為
154
+ 當使用者呼叫 `/adr` 時,AI 助手必須:
174
155
 
175
- When the user invokes `/adr`, the AI assistant MUST:
156
+ 1. **檢查現有 ADR** 搜尋 `docs/adr/` 以確定下一個 ADR 編號
157
+ 2. **互動式引導** — 逐步詢問背景、驅動因素和選項
158
+ 3. **產生檔案** — 將 ADR 寫入 `docs/adr/ADR-NNN-title.md`
159
+ 4. **建議連結** — 識別相關規格或 ADR 以建立交叉引用
160
+ 5. **提供下一步** — 顯示上方的下一步引導
176
161
 
177
- 1. **Check existing ADRs** — Search `docs/adr/` to determine next ADR number
178
- 2. **Guide interactively** — Ask about context, drivers, and options step by step
179
- 3. **Generate the file** — Write ADR to `docs/adr/ADR-NNN-title.md`
180
- 4. **Suggest links** — Identify related SPECs or ADRs to cross-reference
181
- 5. **Offer next steps** — Show the Next Steps Guidance above
162
+ 當使用者呼叫 `/adr list` 時:
163
+ 1. 掃描 `docs/adr/` 目錄
164
+ 2. 解析每個 ADR 檔案的狀態
165
+ 3. 以表格顯示:編號、標題、狀態、日期
182
166
 
183
- When the user invokes `/adr list`:
184
- 1. Scan `docs/adr/` directory
185
- 2. Parse status from each ADR file
186
- 3. Display as a table: Number, Title, Status, Date
167
+ 當使用者呼叫 `/adr supersede [ADR-NNN]` 時:
168
+ 1. 讀取現有 ADR
169
+ 2. 引導建立新 ADR
170
+ 3. 將舊 ADR 狀態更新為 `Superseded by ADR-NNN`
171
+ 4. 在新 ADR 中加入 `Supersedes ADR-NNN`
187
172
 
188
- When the user invokes `/adr supersede [ADR-NNN]`:
189
- 1. Read the existing ADR
190
- 2. Guide creation of a new ADR
191
- 3. Update old ADR status to `Superseded by ADR-NNN`
192
- 4. Add `Supersedes ADR-NNN` to new ADR
193
-
194
- ## Reference | 參考
173
+ ## 參考
195
174
 
196
- - Core Standard: [adr-standards.md](../../core/adr-standards.md)
197
- - Detailed Guide: [guide.md](./guide.md)
175
+ - 核心規範:[adr-standards.md](../../../../core/adr-standards.md)
176
+ - 詳細指南:[guide.md](./guide.md)
@@ -1,9 +1,10 @@
1
1
  ---
2
2
  name: brainstorm-assistant
3
3
  source: ../../../../skills/brainstorm-assistant/SKILL.md
4
- source_version: 1.0.0
5
- translation_version: 1.0.0
6
- last_synced: 2026-02-12
4
+ source_version: 3.0.0
5
+ source_hash: 25e622a7d063
6
+ translation_version: 3.0.0
7
+ last_synced: 2026-06-01
7
8
  status: current
8
9
  description: "[UDS] 在撰寫規格前進行結構化 AI 輔助腦力激盪"
9
10
  ---
@@ -12,96 +13,244 @@ description: "[UDS] 在撰寫規格前進行結構化 AI 輔助腦力激盪"
12
13
 
13
14
  > **語言**: [English](../../../../skills/brainstorm-assistant/SKILL.md) | 繁體中文
14
15
 
15
- 在撰寫規格前進行結構化發想。透過引導式腦力激盪,將模糊構想轉化為可執行的功能提案。
16
+ 在撰寫規格前進行結構化發想。以 2024–2026 年 AI 輔助發想研究為基礎,透過引導式腦力激盪,將模糊構想轉化為可執行的功能提案。
17
+
18
+ > **Implements**: XSPEC-247 brainstorm v3 — Multi-Persona Ensemble + Multi-Critic Convergence
19
+ > (取代 v2「認知科學升級」。)
20
+
21
+ **v3 的核心改動:** v3 把發散從「單一 AI 衝數量」改為 **persona 集成**(每個角色以思維鏈獨立推理)× **多樣性透鏡**;把收斂從「單一 AI 評分 + 單一反駁」改為**多評審面板** + **硬角色反駁**(Devil's Advocate + Steelman)。直接對應文獻最強結論:多 persona 勝過單一 pass,單一 LLM 評審既弱又易諂媚。
22
+
23
+ ## 使用前先選模式
24
+
25
+ 使用前套用以下**客觀觸發條件**。預設為完整 v3,路由規則是跳過階段的快捷鍵,而非額外障礙。
26
+
27
+ | 條件 | 建議模式 | 指令 |
28
+ |------|---------|------|
29
+ | 問題描述少於 20 字**或**主題感覺模糊 | 完整 v3(預設) | `/brainstorm [topic]` |
30
+ | 策略性問題(職涯、架構、商業模式) | 完整 v3 含反駁 | `/brainstorm [topic]` |
31
+ | 宿主支援平行子代理且想要最大多樣性 | 完整 v3 + Enhanced 層 | `/brainstorm --enhanced [topic]` |
32
+ | 純創意(命名、標語、行銷文案) | Lite——跳過反駁 | `/brainstorm --no-rebuttal [topic]` |
33
+ | 時間受限或執行型任務(寫程式碼、修文案) | 快速模式 | `/brainstorm --quick [topic]` |
34
+ | 此主題已有 SDD 規格 | 跳過 pre-flight | `/brainstorm --skip-preflight [topic]` |
35
+
36
+ > **判斷原則:** 不確定適用哪一行時,直接用完整 v3。判斷本身的認知成本高於直接跑完整流程。
16
37
 
17
38
  ## 工作流程
18
39
 
19
40
  ```
20
- FRAME ──► DIVERGE ──► CONVERGE ──► OUTPUT
21
- 定義問題 發散思考 收斂評估 輸出提案
41
+ [Mode Selection] ─► PRE-FLIGHT ─► FRAME ─► DIVERGE ───────────► CONVERGE ──────────► OUTPUT
42
+ 客觀路由 防止錨定 定義問題 persona 集成+透鏡 多評審面板+硬角色反駁 輸出提案
22
43
  ```
23
44
 
24
- ### 階段 1:FRAME | 定義問題
45
+ ---
46
+
47
+ ### Phase 0: PRE-FLIGHT | 防止 AI 錨定
48
+
49
+ **本階段存在的原因:** 在 AI 生成任何內容之前先寫下自己的想法,能持續產出更多樣的結果。在 AI 情境下這**更**重要:設計固著研究顯示,流暢、高擬真的 AI 輸出反而**加深**固著(Wadinambiarachchi 等,CHI 2024)。
50
+
51
+ 在 AI 生成任何內容之前,使用者完成三件事:
52
+
53
+ | 項目 | 提示 |
54
+ |------|------|
55
+ | 1 | 一句話描述問題 |
56
+ | 2 | 3 個初始想法(任意形式、不限品質) |
57
+ | 3 | 「我最不想要的解法類型」(可填 N/A) |
58
+
59
+ **使用者提交後**,AI 讀取全部三項輸入再進入 FRAME。AI 的第一批 DIVERGE 輸出必須探索使用者未提及的方向,且不得重複使用者已提交的想法。
60
+
61
+ > **反種子 guardrail(v3 新增):** 不要用「像 X 但給 Y」的框架當種子(如「給醫生用的 Slack」)。這類產品類比種子會把 LLM 鎖進單一解空間、明顯降低想法多樣性。請捕捉底層**問題**,而非產品類比。
62
+
63
+ **旗標:** `--skip-preflight` 跳過本階段並顯示一行警告:
64
+ `⚠ Skipping Pre-flight may cause AI anchoring`
65
+
66
+ ---
67
+
68
+ ### Phase 1: FRAME | 定義問題
25
69
 
26
70
  在產生想法之前,先清楚定義問題空間。
27
71
 
28
72
  | 步驟 | 動作 |
29
73
  |------|------|
30
74
  | 1 | 用 5 Whys 釐清問題根因 |
31
- | 2 | 重構為「How Might We」(HMW) 問題 |
75
+ | 2 | 重構為 HMW(How Might We)問題 |
32
76
  | 3 | 識別利害關係人與限制條件 |
33
77
  | 4 | 從程式碼庫蒐集脈絡(如適用) |
34
78
 
35
- ### 階段 2:DIVERGE | 發散思考
79
+ ---
80
+
81
+ ### Phase 2: DIVERGE | 發散思考(v3:persona 集成 + 多樣性透鏡)
82
+
83
+ > **v3 核心機制:** **persona 集成**——每個 persona 以**思維鏈**在**隔離**狀態下推理——再乘上**多樣性透鏡**。Meincke、Mollick、Terwiesch(2024)發現「思維鏈 + persona」的想法多樣性高於所有受測提示策略,接近人類團體。光衝數量是弱代理;結構性逼出不同視角才是真正槓桿。
84
+
85
+ #### Step 2a — persona 集成
86
+
87
+ 透過預設 persona 組生成想法。每個 persona **逐步推理(思維鏈)**,**只從自己的視角**產出 2–4 個想法。使用者可用 `--personas` 增減或改名。
88
+
89
+ | 預設 persona | 它所論辯的視角 |
90
+ |-------------|---------------|
91
+ | **Domain expert(領域專家)** | 領域最佳實務要求什麼? |
92
+ | **Skeptic / risk(懷疑者/風險)** | 哪裡會壞?什麼先失敗? |
93
+ | **Cross-domain analogist(跨域類比者)** | 生物/他領域如何解類似問題? |
94
+ | **Cost / constraint(成本/約束)** | 最便宜最小可行解是什麼? |
95
+ | **End-user advocate(使用者代言)** | 真實使用者的感受與需求? |
96
+
97
+ > **分支隔離:** baseline 模式下,生成每個 persona 的想法時**不讓它看到其他 persona 的輸出**,以防止 session 內錨定。等所有 persona 都產完才一起呈現。(Enhanced 層以平行隔離 agent 跑——見下方「Enhanced Tier」。)
98
+
99
+ #### Step 2b — 多樣性透鏡
100
+
101
+ 在 persona 組上至少套用一個透鏡,以突破「顯而易見答案區」。連結異域概念能可量測地提升原創性(Mehrotra、Parab、Gulwani,2024)。
36
102
 
37
- 不加評判地盡可能產生多個想法。
103
+ | 透鏡 | 提示模式 |
104
+ |------|---------|
105
+ | **Analogical / cross-domain(類比/跨域)** | 「在 [生物/物流/遊戲] 中找一個解類似問題的系統。我們能借用什麼?」 |
106
+ | **Assumption reversal(假設反轉)** | 「列出大家都認為必為真的事,再逐一反轉。」 |
107
+ | **Morphological matrix(形態矩陣)** | 「建立三軸矩陣(如 User × Trigger × Constraint),填補罕見組合。」 |
108
+
109
+ 用 `--lens analogical|reversal|morphological` 強制指定某透鏡為主要透鏡。
110
+
111
+ #### Step 2c — 繼續發散提示(輔助)
112
+
113
+ 「好點子在後半」(Nijstad)是**人類群體**現象,**未在 LLM 證實**(LLM 多為高原/枯竭)。故固定數量門檻降為**輔助提示**:若全組少於約 8 個相異想法,提示「繼續——加一個還沒用過的 persona 或透鏡」。真正的門檻是**多樣性**(覆蓋了幾個不同視角),而非數量。
114
+
115
+ #### 經典技法(仍保留)
38
116
 
39
117
  | 技法 | 使用時機 |
40
118
  |------|----------|
41
- | **HMW 問題** | 預設起點 |
119
+ | **HMW Questions** | 預設起點 |
42
120
  | **SCAMPER** | 改善現有功能 |
43
- | **六頂思考帽** | 需要多角度思考 |
121
+ | **Six Thinking Hats** | 需要多角度(很適合當 persona) |
44
122
 
45
- ### 階段 3:CONVERGE | 收斂評估
123
+ ---
46
124
 
47
- 使用結構化標準評估與排序想法。
125
+ ### Phase 3: CONVERGE | 收斂(v3:多評審面板 + 硬角色反駁)
48
126
 
49
- | 評估標準 | 權重 |
50
- |----------|------|
51
- | 技術可行性 | 30% |
52
- | 使用者影響力 | 30% |
53
- | 實作成本 | 20% |
54
- | 目標一致性 | 20% |
127
+ > **v3 核心機制:** **多評審面板**取代單一加權評分者。單一 LLM 是弱且有偏的評估者(Li 等,2025:LLM 強於生成/精煉、弱於評估——人類保留最終裁決權)。三個獨立評審透鏡各自評分後聚合。
55
128
 
56
- ### 階段 4:OUTPUT | 輸出提案
129
+ #### Step 3a: 多評審面板
57
130
 
58
- 產生可直接對接 `/requirement` 或 `/sdd` 的腦力激盪報告。
131
+ 跑**三個獨立評審**,各自以自己的透鏡對每個想法打 1–5 分;取平均聚合以降低單評審偏誤。每位評審皆套用下方加權公式。
59
132
 
60
- ## 技法速覽
133
+ | 評審透鏡 | 它所負責的加權準則 |
134
+ |---------|-------------------|
135
+ | **Engineering feasibility(工程可行性)** | Feasibility 50% · Effort 50% |
136
+ | **User impact(使用者影響)** | Impact 70% · Alignment 30% |
137
+ | **Strategic alignment(策略一致性)** | Alignment 60% · Impact 40% |
138
+
139
+ 各準則評分指南(1–5):Feasibility(5=輕而易舉 … 1=幾乎不可能);Impact(5=變革性 … 1=可忽略);Effort(5=數小時 … 1=數季,反向計分,工作量越低分越高);Alignment(5=核心使命 … 1=偏離使命)。
140
+
141
+ > **可選——RICE / ICE(產品功能):** 排序可出貨功能時用 `RICE =(Reach × Impact × Confidence)/ Effort` 或較輕的 `ICE = Impact × Confidence × Ease`。Effort 交由工程師估、不要讓 LLM 估(它無程式庫知識)。RICE 偏好漸進式勝利,別單獨用於策略性押注。
142
+
143
+ #### Step 3b: 硬角色反駁輪
61
144
 
62
- | 技法 | 用途 | 步驟 |
63
- |------|------|------|
64
- | **5 Whys** | 根因分析 | 連問 5 次「為什麼?」 |
65
- | **HMW** | 問題重構 | 「我們如何能 [動詞] [成果]?」 |
66
- | **SCAMPER** | 創意改造 | 7 步驟:替代、結合、調適、修改、另作他用、刪除、反轉 |
67
- | **六頂思考帽** | 多角度思考 | 6 種模式:事實、情感、風險、好處、創意、流程 |
68
- | **點數投票** | 快速排序 | 每人 3 票,投給最看好的想法 |
145
+ 軟性「請批評一下」只會得到附和(諂媚)。v3 指派**硬角色**:對**前三名想法**各跑一個 **Devil's Advocate**(「你的任務是論證此案會失敗」)與一個 **Steelman**(「說出反方最強而善意的版本」)。兩者一起壓力測試韌性,而非只是戳。
146
+
147
+ 每個反對理由須為:「在 [具體情境] 下,此想法會失敗,因為 [具體原因]。」模糊顧慮(「這可能有點難」)不接受。
148
+
149
+ 使用者**必須**對每個給出回應才能繼續:
150
+
151
+ | 選項 | 動作 |
152
+ |------|------|
153
+ | (a) | 接受批評 → 提供修改版本 |
154
+ | (b) | 不同意 → 給具體保留理由 |
155
+ | (c) | 批評成立 → 從排名移除 |
156
+
157
+ **旗標:** `--no-rebuttal` 跳過此步驟;報告段落標注「Rebuttal: skipped」。
158
+
159
+ ---
160
+
161
+ ### Phase 4: OUTPUT | 輸出提案
162
+
163
+ 產生可直接對接 `/requirement` 或 `/sdd` 的腦力激盪報告。每個存活想法標記 `✓ Passed rebuttal`、使用者回應摘要、來源 persona/透鏡、以及聚合評審分數。
69
164
 
70
165
  ## 輸出格式
71
166
 
72
167
  ```markdown
73
- # 腦力激盪報告:[主題]
74
-
75
- ## 問題陳述
76
- [FRAME 階段精煉的問題]
77
-
78
- ## HMW 問題
79
- 1. 我們如何能...?
80
- 2. 我們如何能...?
81
- 3. 我們如何能...?
82
-
83
- ## 產生的想法
84
- | # | 想法 | 來源技法 | 可行性 | 影響力 | 分數 |
85
- |---|------|----------|--------|--------|------|
86
- | 1 | ... | SCAMPER | 4/5 | 5/5 | 4.3 |
87
- | 2 | ... | HMW | 3/5 | 4/5 | 3.5 |
88
-
89
- ## 3 名推薦
90
- 1. **[想法名稱]**[推薦原因]
91
- 2. **[想法名稱]** — [推薦原因]
92
- 3. **[想法名稱]** [推薦原因]
93
-
94
- ## 後續步驟
95
- - [ ] 以首選想法進入 `/requirement`
96
- - [ ] 若需求已明確,直接進入 `/sdd`
97
- - [ ] 需進一步探索想法 #N
168
+ # Brainstorm Report: [Topic]
169
+
170
+ ## Problem Statement
171
+ [Refined problem + root cause from FRAME]
172
+
173
+ ## HMW Questions
174
+ 1. How might we ...?
175
+
176
+ ## Ideas Generated
177
+ | # | Idea | Persona | Lens | Critic-Feas | Critic-Impact | Critic-Align | Agg. Score |
178
+ |---|------|---------|------|-------------|---------------|--------------|-----------|
179
+ | 1 | ... | Skeptic | Reversal | 4.0 | 4.5 | 4.0 | 4.2 |
180
+
181
+ ## Top 3 Recommendations
182
+ 1. **[Idea]** Passed rebuttal [Why] — Persona: [..] — [User rebuttal response]
183
+
184
+ ## Diversity Note
185
+ [How many distinct lenses/personas the surviving ideas span flag if all from one cluster]
186
+
187
+ ## Discarded Ideas (with reasons)
188
+ | Idea | Reason |
189
+
190
+ ## Next Steps
191
+ - [ ] Proceed to `/requirement` with top idea
192
+ - [ ] Proceed to `/sdd` if requirements are clear
98
193
  ```
99
194
 
195
+ ## 多樣性崩塌防護
196
+
197
+ 用單一 LLM 發想會降低**跨使用者的想法多樣性**,即使個人覺得更有創意(Anderson、Shah、Kreminski,2024;與廣為引用的 Doshi & Hauser,《Science Advances》2024 同向)。防範方式:
198
+
199
+ - **絕不**用競品或產品類比當種子(「像 X 但給 Y」)。
200
+ - 變的是**透鏡**而非措辭——換句話不等於多樣化。
201
+ - 若存活的前三名全來自同一 persona/透鏡,**標示**並在輸出前再跑一個透鏡。
202
+
203
+ ## 強化層——平行 persona
204
+
205
+ 多 agent 發想(獨立 agent 互相對話/貢獻)在感知品質與新穎度上勝過單 agent(Quan 等,2025,*MultiColleagues*)。在支援平行子代理的宿主(如 Claude Code 的 Agent/Workflow 工具),`--enhanced` 會把每個 persona 與每個評審當作**平行、context 隔離的 agent** 跑,再合併去重。
206
+
207
+ > **優雅降級:** 此層為**可選**。在無子代理的宿主,`--enhanced` 靜默退回 baseline(單 context 模擬 persona)。本 skill 維持 `scope: universal`。
208
+
209
+ ## 技法速覽
210
+
211
+ | 技法 | 用途 |
212
+ |------|------|
213
+ | **5 Whys** | 根因分析 |
214
+ | **HMW** | 問題重構 |
215
+ | **Persona ensemble** | 強制視角多樣性(v3 核心) |
216
+ | **Diversity lenses** | 突破顯而易見區(analogical / reversal / morphological) |
217
+ | **Multi-critic panel** | 降偏誤評分(v3 核心) |
218
+ | **Devil's Advocate + Steelman** | 硬角色反駁 |
219
+ | **SCAMPER / Six Hats** | 經典發散(可當 persona) |
220
+
221
+ ## 工作階段自評
222
+
223
+ 每次工作階段結束後記錄三個指標(1–5 分),追蹤長期改善。
224
+
225
+ | 指標 | 問題 |
226
+ |------|------|
227
+ | **Adoption Rate(採用率)** | 今天的想法我實際會用幾個? |
228
+ | **Diversity(多樣性)** | 存活想法跨越多個 persona/透鏡嗎? |
229
+ | **Cognitive Load(認知負擔)** | 這過程心智上有多累?(5 = 毫不費力) |
230
+
231
+ 收集 3 次工作階段資料再下結論。完整 A/B 實驗協議見 [guide.md](./guide.md)。
232
+
233
+ ## 旗標
234
+
235
+ | 旗標 | 說明 |
236
+ |------|------|
237
+ | `--personas "a,b,c"` | 覆寫預設 persona 組 |
238
+ | `--lens analogical\|reversal\|morphological` | 指定主要多樣性透鏡 |
239
+ | `--enhanced` | 平行 persona/評審 agent(不支援則退回) |
240
+ | `--skip-preflight` | 跳過 Phase 0,顯示錨定警告 |
241
+ | `--no-rebuttal` | 跳過 CONVERGE 反駁輪,報告標注 skipped |
242
+ | `--quick` | 快速 3 想法模式;門檻與反駁均豁免 |
243
+ | `--technique scamper` | 強制使用 SCAMPER 為主要技法 |
244
+
100
245
  ## 使用方式
101
246
 
102
- - `/brainstorm` — 啟動互動式腦力激盪
103
- - `/brainstorm "用戶留存"` — 針對特定主題進行腦力激盪
104
- - `/brainstorm --technique scamper` — 使用特定技法
247
+ - `/brainstorm` — 啟動互動式腦力激盪工作階段
248
+ - `/brainstorm "user retention"` — 針對特定主題腦力激盪
249
+ - `/brainstorm --enhanced "user retention"` — 平行 persona 集成(若宿主支援)
250
+ - `/brainstorm --personas "designer,economist,skeptic" "pricing"` — 自訂 persona
251
+ - `/brainstorm --lens analogical "onboarding"` — 強制類比透鏡
252
+ - `/brainstorm --quick "reduce checkout friction"` — 快速 3 想法模式
253
+ - `/brainstorm --no-rebuttal "topic"` — 跳過反駁輪
105
254
 
106
255
  ## 下一步引導
107
256
 
@@ -109,9 +258,13 @@ FRAME ──► DIVERGE ──► CONVERGE ──► OUTPUT
109
258
 
110
259
  > **腦力激盪完成。建議下一步:**
111
260
  > - 執行 `/requirement` 將最佳構想轉為使用者故事
112
- > - 執行 `/sdd` 直接建立規格(若需求已明確)
261
+ > - 執行 `/sdd` 直接建立規格(若需求已明確)⭐ **推薦**
113
262
  > - 針對特定構想進行更深入探索
114
263
 
115
264
  ## 參考
116
265
 
117
266
  - 詳細指南:[guide.md](./guide.md)
267
+
268
+ ## AI 代理行為
269
+
270
+ > 完整的 AI 行為定義請參閱對應的命令文件:[`/brainstorm`](../commands/brainstorm.md#ai-agent-behavior--ai-代理行為)