universal-dev-standards 5.15.1 → 5.17.0

package/bundled/locales/zh-TW/skills/observability-assistant/guide.md

@@ -0,0 +1,188 @@
+---
+source: ../../../../skills/observability-assistant/guide.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-06-02
+source_hash: 760e3ec43846
+status: current
+scope: universal
+description: |
+  引導跨三大支柱的 observability 實作：Logs、Metrics 與 Traces。
+  使用時機：建立監控、選擇 metric 類型、實作 tracing、評估成熟度。
+  關鍵字：observability, metrics, traces, logs, golden signals, OpenTelemetry, 可觀測性, 監控。
+---
+
+# Observability Assistant
+
+> **語言**：[English](../../../../skills/observability-assistant/guide.md) | 繁體中文
+
+**版本**：1.0.0
+**最後更新**：2026-04-01
+**適用範圍**：Claude Code Skills
+
+---
+
+## 用途
+
+本 skill 透過提供三大支柱（Logs、Metrics、Traces）、metric 類型選擇、Golden Signals 監控與成熟度自我評估的指引，協助團隊建構可觀測的系統。
+
+---
+
+## 快速參考（YAML 壓縮版）
+
+```yaml
+# === THREE PILLARS 三大支柱 ===
+three_pillars:
+  logs:
+    captures: "Discrete events with context / 帶上下文的離散事件"
+    use_for: "Debugging, audit trails, error details"
+    granularity: "High (per-event)"
+  metrics:
+    captures: "Numerical measurements over time / 隨時間變化的數值量測"
+    use_for: "Dashboards, alerting, capacity planning"
+    granularity: "Low (aggregated)"
+  traces:
+    captures: "Request flow across services / 跨服務的請求流"
+    use_for: "Latency analysis, dependency mapping"
+    granularity: "Medium (per-request)"
+
+correlation:
+  metric_to_trace: "Use Exemplars to link anomalous metric → specific trace"
+  trace_to_logs: "Use trace_id + span_id embedded in logs"
+  logs_to_metric: "Aggregate log patterns into metrics (e.g., error rate)"
+  key_fields: ["trace_id", "service.name"]
+
+# === METRIC TYPES 指標類型 ===
+metric_types:
+  counter:
+    behavior: "Monotonically increasing (resets on restart) / 只增不減"
+    examples: ["request count", "error count", "bytes sent"]
+  gauge:
+    behavior: "Point-in-time value, can go up or down / 當前值，可升可降"
+    examples: ["temperature", "queue depth", "active connections"]
+  histogram:
+    behavior: "Distribution across buckets / 跨桶分布"
+    examples: ["request duration", "response size"]
+  summary:
+    behavior: "Client-computed percentiles / 客戶端計算百分位"
+    examples: ["legacy systems needing client-side quantiles"]
+
+metric_type_decision:
+  only_goes_up: "→ Counter"
+  need_distribution: "→ Histogram"
+  current_state_value: "→ Gauge"
+  legacy_client_percentiles: "→ Summary"
+
+naming: "<domain>.<entity>.<action>.<unit>"
+# e.g., http.server.request.duration.seconds
+
+# === GOLDEN SIGNALS 黃金信號 ===
+golden_signals:
+  latency:
+    what: "Request duration P50/P95/P99 / 請求延遲"
+    metric: "http.server.request.duration.seconds"
+    alert: "P99 > threshold sustained 5 min"
+  traffic:
+    what: "Requests per second (RPS) / 每秒請求數"
+    metric: "http.server.request.total (Counter, rate)"
+    alert: "Sudden drop >50% or spike >200%"
+  errors:
+    what: "Error rate = 5xx / total / 錯誤率"
+    metric: "http.server.request.total{status=~'5..'}"
+    alert: "Error rate > X% sustained 5 min"
+  saturation:
+    what: "Resource utilization / 資源飽和度"
+    metrics: ["system.cpu.utilization", "system.memory.utilization", "db.client.connection.pool.usage"]
+    alert: "Resource > 80% sustained 10 min"
+
+# === MATURITY MODEL 成熟度模型 ===
+maturity:
+  L0_no_observability:
+    characteristics: "No structured logs; debugging via SSH + tail -f / 無結構化日誌"
+    upgrade: "Implement structured logging; centralize collection"
+  L1_basic_logging:
+    characteristics: "Structured JSON logs; centralized; basic search / 結構化日誌+集中收集"
+    upgrade: "Add business metrics; create first dashboard"
+  L2_metrics_driven:
+    characteristics: "Logs + Metrics; dashboards; basic alerting / 日誌+指標+儀表板"
+    upgrade: "Enable distributed tracing; SLO-based alerting"
+  L3_full_observability:
+    characteristics: "All three pillars; correlation; SLO alerts; Golden Signals / 三支柱完整"
+    upgrade: "Add anomaly detection; auto-remediation"
+  L4_intelligent:
+    characteristics: "AIOps; predictive alerting; automatic remediation / 智慧化可觀測"
+    upgrade: "Maintain, optimize, share learnings"
+
+self_assessment:
+  - "Can you find logs for a specific request across all services? (L1+)"
+  - "Can you view dashboards showing error rate and latency? (L2+)"
+  - "Can you trace a request from ingress to database and back? (L3+)"
+  - "Does your system auto-detect anomalies before users report? (L4)"
+
+# === INSTRUMENTATION CHECKLIST 儀器化清單 ===
+pre_production_checklist:
+  - "Structured logging enabled (JSON + trace_id)"
+  - "HTTP/gRPC entry metrics (count, duration histogram, error rate)"
+  - "Critical business operation custom metrics"
+  - "Distributed tracing enabled (sampling rate set, W3C headers)"
+  - "Health check endpoints (liveness + readiness)"
+  - "Dashboard covering Golden Signals"
+  - "Alert rules defined (SLO burn rate)"
+  - "Log retention configured"
+  - "Sensitive data excluded from logs/traces"
+```
+
+---
+
+## 與相關技能整合 / Integration with Related Skills
+
+| Skill | 整合點 | 說明 |
+|-------|-------------------|-------------|
+| `/slo` | 以 SLO 為基礎的告警 | 以 metrics 作為 SLI 資料來源；burn rate 告警參照 Golden Signals |
+| `/incident` | 事件診斷 | 三大支柱提供診斷資料；correlation 加速 MTTD/MTTR |
+| `/observability --alerting` | 告警設計 | Golden Signals 引導告警規則建立 |
+
+---
+
+## 設定偵測
+
+### 偵測順序
+
+1. 檢查 `CONTRIBUTING.md` 是否有「Disabled Skills」段落
+2. 檢查 `CONTRIBUTING.md` 是否有「Observability Standards」段落
+3. 若未找到，**預設採用標準 observability 實務**
+
+---
+
+## 詳細指引
+
+完整標準請參閱：
+- [Observability Standards](../../core/observability-standards.md)
+- [Logging Standards](../../core/logging-standards.md)
+
+---
+
+## 相關標準
+
+- [Observability Standards](../../core/observability-standards.md) - 核心標準
+- [SLO Standards](../../core/slo-standards.md) - SLI/SLO/Error Budget
+- [Alerting Standards](../../core/alerting-standards.md) - 告警設計
+- [Performance Standards](../../core/performance-standards.md) - 效能目標
+- [SLO Assistant](../slo-assistant/SKILL.md) - SLO 工作流程
+- [Runbook Assistant](../runbook-assistant/SKILL.md) - 維運程序
+
+---
+
+## 版本歷史
+
+| 版本 | 日期 | 變更 |
+|---------|------|---------|
+| 1.0.0 | 2026-04-01 | 初版發布 |
+
+---
+
+## 授權
+
+本 skill 以 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 釋出。
+
+**來源**：[universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)

package/bundled/locales/zh-TW/skills/orchestrate/SKILL.md

@@ -2,8 +2,9 @@
 name: orchestrate
 source: ../../../../skills/orchestrate/SKILL.md
 source_version: 2.0.0
-translation_version: 1.0.0
-last_synced: 2026-05-28
+translation_version: 2.0.0
+last_synced: 2026-06-02
+source_hash: 40e97479c7da
 scope: universal
 description: |
   [UDS] 以 Claude 原生 Agent tool 編排多任務執行計畫（DAG-based，無外部引擎）。

package/bundled/locales/zh-TW/skills/plan/SKILL.md

@@ -2,8 +2,9 @@
 name: plan
 source: ../../../../skills/plan/SKILL.md
 source_version: 2.0.0
-translation_version: 1.0.0
-last_synced: 2026-05-28
+translation_version: 2.0.0
+last_synced: 2026-06-02
+source_hash: 6fbb1a1b8040
 scope: universal
 description: |
   [UDS] 從 Spec 文件、OpenSpec 變更或自由文字需求生成 plan.json。

package/bundled/locales/zh-TW/skills/push/SKILL.md

@@ -2,8 +2,9 @@
 name: push
 source: ../../../../skills/push/SKILL.md
 source_version: 2.0.0
-translation_version: 1.0.0
-last_synced: 2026-05-28
+translation_version: 2.0.0
+last_synced: 2026-06-02
+source_hash: b7812535483c
 scope: universal
 description: |
   [UDS] AI 輔助 git push 安全層：品質閘門 + 協作護欄。

package/bundled/locales/zh-TW/skills/retrospective-assistant/SKILL.md

@@ -2,17 +2,61 @@
 name: retrospective-assistant
 source: ../../../../skills/retrospective-assistant/SKILL.md
 source_version: 1.0.0
+source_hash: 9c883f05ad7b
 translation_version: 1.0.0
-last_synced: 2026-03-26
+last_synced: 2026-06-01
 status: current
-description: "[UDS] 引導結構化的團隊回顧，支援 Sprint 和 Release 回顧"
+description: "[UDS] 引導 Sprint 與 Release 週期的結構化團隊回顧"
 ---
 
 # 回顧助手
 
 > **語言**: [English](../../../../skills/retrospective-assistant/SKILL.md) | 繁體中文
 
-引導結構化的團隊回顧，識別改善機會並追蹤行動項目。
+引導結構化的團隊回顧，識別改善機會並追蹤行動項目。支援 Sprint 和 Release 回顧類型，提供多種引導技法。
+
+## 工作流程
+
+```
+PREPARE ──► GATHER ──► ANALYZE ──► DECIDE ──► TRACK
+  準備資料    蒐集意見    分析歸納    決定行動    追蹤落實
+```
+
+### 階段 1：PREPARE（準備）
+
+從 git log、指標和 issue tracker 蒐集數據作為討論基礎。
+
+### 階段 2：GATHER（蒐集）
+
+使用結構化技法蒐集團隊觀點。
+
+### 階段 3：ANALYZE（分析）
+
+分組歸納並識別模式。
+
+### 階段 4：DECIDE（決定）
+
+選出前 1-3 項改善作為行動項目。
+
+### 階段 5：TRACK（追蹤）
+
+檢視過去的行動項目並追蹤新項目。
+
+## 回顧類型
+
+| 類型 | 時機 | 時長 | 焦點 |
+|------|------|------|------|
+| **Sprint** | 迭代結束 | 30-60 分鐘 | 流程、協作、工具 |
+| **Release** | 發布之後 | 60-90 分鐘 | 品質、指標、跨團隊 |
+
+## 引導技法
+
+| 技法 | 適用場景 | 結構 |
+|------|---------|------|
+| **Start-Stop-Continue** | 快速、預設 | 開始 / 停止 / 繼續 |
+| **Starfish** | 細緻分析 | 更多 / 保持 / 減少 / 開始 / 停止 |
+| **4Ls** | 團隊建立 | 喜歡 / 學到 / 缺少 / 渴望 |
+| **Sailboat** | 視覺化、創意 | 風 / 錨 / 礁石 / 島嶼 |
 
 ## 指令
 
@@ -24,21 +68,43 @@ description: "[UDS] 引導結構化的團隊回顧，支援 Sprint 和 Release
 | `/retrospective actions` | 列出未完成行動項目 |
 | `/retrospective --technique starfish` | 使用指定技法 |
 
-## 參考
+## 行動項目格式
 
-- 核心規範：[retrospective-standards.md](../../../../core/retrospective-standards.md)
-- 詳細指南：[guide.md](./guide.md)
+| 欄位 | 說明 |
+|------|------|
+| **Action** | 具體描述 |
+| **Owner** | 單一負責人 |
+| **Due Date** | 預計完成日 |
+| **Status** | Open → In Progress → Done |
 
+### 追蹤規則
 
-## Next Steps Guidance | 下一步引導
+1. 每次回顧**開始**先檢視未完成項目
+2. 每次回顧最多 **3 項**行動項目
+3. 陳舊項目（超過 2 個循環未完成）須重新評估
+4. 每項須有**單一負責人**
 
-After `/retrospective` completes:
+## 存放
 
-> **Retrospective complete. Suggested next steps:**
-> - Commit the retrospective report: `/commit`
-> - Create ADRs for architectural decisions identified: `/adr`
-> - Track action items in your issue tracker
-> - Schedule next retrospective
+```
+docs/retrospectives/
+├── RETRO-2026-03-15-sprint-12.md
+├── RETRO-2026-03-26-release-v5.1.0.md
+└── README.md    # 索引（選用）
+```
+
+## 與其他技能的整合
+
+| 技能 | 整合方式 |
+|------|---------|
+| `/metrics` | 將指標數據引入 Release 回顧 |
+| `/incident` | 事故後建議進行團隊回顧 |
+| `/adr` | 識別架構問題時建議建立 ADR |
+| `/commit` | 以 `docs(retro):` 提交回顧報告 |
+
+## 下一步引導
+
+`/retrospective` 完成後：
 
 > **回顧完成。建議下一步：**
 > - 提交回顧報告：`/commit`
@@ -46,23 +112,23 @@ After `/retrospective` completes:
 > - 在 issue tracker 中追蹤行動項目
 > - 排定下次回顧
 
-## AI Agent Behavior | AI 代理行為
+## AI 代理行為
 
-When `/retrospective` is invoked:
+當呼叫 `/retrospective` 時：
 
-1. **Check type** — Sprint (default) or Release
-2. **Gather data** — Scan git log, check `docs/retrospectives/` for previous actions
-3. **Guide technique** — Use Start-Stop-Continue by default, or specified technique
-4. **Generate report** — Write to `docs/retrospectives/RETRO-YYYY-MM-DD-[type].md`
-5. **Review past actions** — Check previous retro for open action items
-6. **Offer next steps** — Show guidance above
+1. **確認類型** — Sprint（預設）或 Release
+2. **蒐集數據** — 掃描 git log，檢查 `docs/retrospectives/` 中過去的行動項目
+3. **引導技法** — 預設使用 Start-Stop-Continue，或使用指定技法
+4. **產生報告** — 寫入 `docs/retrospectives/RETRO-YYYY-MM-DD-[type].md`
+5. **檢視過去項目** — 檢查先前回顧中未完成的行動項目
+6. **提供下一步** — 顯示上方引導
 
-When `/retrospective actions` is invoked:
-1. Scan `docs/retrospectives/` for all retro files
-2. Parse action items from each
-3. Display open/in-progress items as table
+當呼叫 `/retrospective actions` 時：
+1. 掃描 `docs/retrospectives/` 中所有回顧檔案
+2. 解析各檔案中的行動項目
+3. 以表格顯示未完成／進行中的項目
 
-## Reference | 參考
+## 參考
 
-- Core Standard: [retrospective-standards.md](../../core/retrospective-standards.md)
-- Detailed Guide: [guide.md](./guide.md)
+- 核心規範：[retrospective-standards.md](../../core/retrospective-standards.md)
+- 詳細指南：[guide.md](./guide.md)

package/bundled/locales/zh-TW/skills/reverse-engineer/SKILL.md

@@ -2,48 +2,94 @@
 name: reverse-engineer
 source: ../../../../skills/reverse-engineer/SKILL.md
 source_version: 1.2.0
+source_hash: d543b24b2422
 translation_version: 1.2.0
-last_synced: 2026-02-10
+last_synced: 2026-06-01
 status: current
-description: "[UDS] 將現有程式碼反向工程為規格文件、BDD 場景或 TDD 覆蓋率報告"
+description: "[UDS] 系統考古——跨邏輯、資料、執行環境三維度反向工程程式碼"
 ---
 
 # 反向工程助手
 
 > **語言**: [English](../../../../skills/reverse-engineer/SKILL.md) | 繁體中文
 
-將現有程式碼反向工程為規格文件、BDD 場景或 TDD 覆蓋率報告。
+系統考古框架：從三個維度反向工程既有系統——**邏輯**、**資料**、**執行環境**。
+
+## 三大維度
+
+```
+┌─────────────────────────────────────────────────────────┐
+│              System Archeology Framework                   │
+├──────────┬──────────────┬────────────────────────────────┤
+│  Logic   │     Data     │          Runtime               │
+│ (spec)   │    (data)    │         (runtime)              │
+├──────────┼──────────────┼────────────────────────────────┤
+│ APIs     │ DB Schemas   │ Logs & Error Patterns          │
+│ Modules  │ ORMs/Models  │ Config & Environment           │
+│ Flows    │ Migrations   │ Metrics & Performance          │
+│ Tests    │ Seed Data    │ Infra & Deployment             │
+└──────────┴──────────────┴────────────────────────────────┘
+```
 
 ## 子命令
 
-| 子命令 | 輸入 | 輸出 | 說明 |
-|--------|------|------|------|
-| `spec` | 程式碼檔案/目錄 | `SPEC-XXX.md` | 從程式碼提取規格 |
-| `bdd` | `SPEC-XXX.md` | `.feature` | 將 AC 轉為 Gherkin |
-| `tdd` | `.feature` | 覆蓋率報告 | 分析測試覆蓋率 |
+| 子命令 | 維度 | 輸入 | 輸出 | 說明 |
+|--------|------|------|------|------|
+| *(無)* | 全部 | 專案根目錄 | 完整考古報告 | 三維度全面分析 |
+| `spec` | 邏輯 | 程式碼檔案/目錄 | `SPEC-XXX.md` | 從程式碼提取規格 |
+| `data` | 資料 | DB 結構、ORM、遷移檔 | 資料模型規格 | 分析資料模型與結構 |
+| `runtime` | 執行環境 | 日誌、設定、指標 | 執行環境基準 | 分析執行環境基準 |
+| `bdd` | — | `SPEC-XXX.md` | `.feature` | 將 AC 轉為 Gherkin |
+| `tdd` | — | `.feature` | 覆蓋率報告 | 分析測試覆蓋率 |
+
+## 全面分析模式
+
+當 `/reverse` 在未帶子命令的情況下被呼叫時，依序執行全部三個維度：
+
+1. **資料（Data）** → 掃描結構、ORM、遷移檔
+2. **執行環境（Runtime）** → 分析日誌、設定、部署
+3. **邏輯（Logic / spec）** → 提取 API、流程、測試 → 產生 SPEC
+
+輸出：整合三個維度的 **系統考古報告（System Archeology Report）**。
 
-## 工作流程
+## 維度詳情
 
-### spec：程式碼轉規格
+### spec：邏輯維度（既有）
 
-1. **掃描** - 讀取原始碼檔案，識別公開 API、資料流和業務邏輯
+1. **掃描** - 讀取原始碼檔案，識別公開 API、資料流與業務邏輯
 2. **分類** - 將每個發現標記為 `[Confirmed]`、`[Inferred]` 或 `[Unknown]`
 3. **結構化** - 整理為 SDD 規格格式，包含驗收條件
-4. **引用來源** - 每個反向結果皆引用 `file:line` 來源參考
+4. **引用來源** - 每項反向結果皆以 `file:line` 引用來源
 
-### bdd：規格轉 Gherkin
+### data：資料維度（新增）
 
-1. **解析** - 讀取 SPEC-XXX.md 並提取驗收條件
-2. **轉換** - 將每個 AC 對應為一個 Gherkin Scenario（1:1 對應）
-3. **標記** - 加入 `@SPEC-XXX` 和 `@AC-N` 標籤以確保可追溯性
-4. **輸出** - 產生 `.feature` 檔案，包含 `# [Source: path:AC-N]` 註解
+1. **探索** - 找出資料庫結構、ORM 模型、遷移檔、種子資料
+2. **對應** - 從程式碼證據建立實體關聯模型
+3. **分類** - 將關聯標記為 `[Confirmed]`（FK 約束）或 `[Inferred]`（程式碼模式）
+4. **報告** - 輸出資料模型規格，包含：
+   - 含欄位與型別的實體清單
+   - 關聯對應（1:1、1:N、M:N）
+   - 索引與約束清單
+   - 遷移歷史摘要
+   - 資料流路徑（寫入 → 讀取）
 
-### tdd：Feature 轉覆蓋率報告
+**證據來源**：`schema.prisma`、`*.migration.*`、`models/`、`entities/`、`knexfile.*`、`sequelize`、`typeorm`、SQL 檔案、`docker-compose.yml`（DB 服務）
 
-1. **解析** - 讀取 `.feature` 檔案中的場景
-2. **搜尋** - 使用 Grep/Glob 尋找對應的測試檔案
-3. **對應** - 將場景與現有單元測試進行配對
-4. **報告** - 輸出覆蓋率矩陣（已覆蓋 / 缺失 / 部分覆蓋）
+### runtime：執行環境維度（新增）
+
+1. **掃描設定** - 環境變數、設定檔、功能旗標
+2. **分析日誌** - 日誌模式、錯誤頻率、日誌層級
+3. **檢查基礎設施** - Docker 設定、CI/CD 管線、部署清單
+4. **建立基準** - 輸出執行環境基準，包含：
+   - 環境變數清單（僅名稱，**絕不含值/密鑰**）
+   - 設定檔對應與階層
+   - 外部服務依賴（API、佇列、快取）
+   - 部署拓撲（容器、服務）
+   - 健康檢查與監控端點
+
+**證據來源**：`.env.example`、`docker-compose.yml`、`Dockerfile`、`*.config.*`、CI/CD 檔案、`k8s/`、日誌檔案（僅模式）
+
+**安全性**：絕不輸出實際密鑰值。僅列出變數名稱並描述其用途。
 
 ## 防幻覺規則
 
@@ -52,23 +98,33 @@ description: "[UDS] 將現有程式碼反向工程為規格文件、BDD 場景
 | **確定性標籤** | 所有發現須使用 `[Confirmed]`、`[Inferred]`、`[Unknown]` 標注 |
 | **來源引用** | 每項反向結果須引用 `file:line` 來源 |
 | **禁止捏造** | 不得捏造程式碼中不存在的 API 或行為 |
+| **禁止密鑰** | 不得輸出設定檔或環境變數的密鑰值 |
 
 ## 使用方式
 
-- `/reverse spec src/auth/` - 從 auth 模組提取規格
-- `/reverse bdd specs/SPEC-AUTH.md` - 將規格 AC 轉為 Gherkin 場景
-- `/reverse tdd features/auth.feature` - 分析 feature 檔案的測試覆蓋率
+```
+/reverse                              - 三維度全面分析
+/reverse spec src/auth/               - 邏輯：提取規格
+/reverse data                         - 資料：分析結構與模型
+/reverse runtime                      - 執行環境：分析設定與基礎設施
+/reverse bdd specs/SPEC-AUTH.md       - 將規格 AC 轉為 Gherkin
+/reverse tdd features/auth.feature    - 分析測試覆蓋率
+```
 
 ## 下一步引導
 
 `/reverse`（完整或 `spec`）完成後，AI 助手應建議：
 
 > **系統考古完成。建議下一步：**
-> - 執行 `/sdd` 審查並核准此規格
-> - 執行 `/derive` 從規格推導測試
-> - 審查規格中的 `[Inferred]` 和 `[Unknown]` 標記
+> - 執行 `/sdd` 審查並核准此規格 ⭐ **推薦** — 審查並核准產生的規格
+> - 執行 `/derive` 從規格推導測試 — 從規格推導測試（須先核准）
+> - 審查規格中的 `[Inferred]` 和 `[Unknown]` 標記 — 手動審查不確定性標籤
 
 ## 參考
 
 - 詳細指南：[guide.md](./guide.md)
 - 核心規範：[reverse-engineering-standards.md](../../../../core/reverse-engineering-standards.md)
+
+## AI 代理行為
+
+> 完整的 AI 行為定義請參閱對應的命令文件：[`/reverse`](../commands/reverse.md#ai-agent-behavior--ai-代理行為)