universal-dev-standards 5.13.3 → 5.15.1

package/bundled/locales/zh-TW/skills/skill-builder/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: skill-builder
+source: ../../../../skills/skill-builder/SKILL.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-05-28
+scope: universal
+description: "[UDS] 識別重複流程並以正確開發深度建立 Skill"
+allowed-tools: Read, Glob, Grep, Write, Edit, Bash
+argument-hint: "[流程描述]"
+---
+
+# 流程轉 Skill 助手
+
+> **語言**: [English](../../../../skills/skill-builder/SKILL.md) | 繁體中文
+
+引導你從「我一直手動做這件事」走到「擁有一個正確建立的 Skill」，並在過程中保持適量的流程治理。
+
+## 何時使用
+
+- 你已經用同樣的多步驟流程手動執行 ≥ 3 次
+- 同事第 3 次問你「我們是怎麼做 X 的？」
+- 你臨時建了一個 Skill，現在想將其正式化
+
+> **備註**：`/process-to-skill` 是本 Skill 的繁體中文翻譯版，功能完全相同。
+
+## 核心原則
+
+> Skill 紀錄的是**流程知識**。Memory 紀錄的是歷史事實。
+> 當你注意到自己重複執行相同的步驟，那就是 Skill 候選。
+
+## 決策樹
+
+```
+需要新建 Skill？
+├── 修改現有 Skill？
+│     → Delta 路徑：在現有 SKILL.md 後附加 ## MODIFIED / ## ADDED
+│                   更新 version 欄位 → 完成
+│
+├── 回答這 4 個問題（任一「是」→ Complex）：
+│     1. 超過 7 個步驟？
+│     2. 步驟之間有分支邏輯（if / else）？
+│     3. 需要 3+ 不同標準／決策的知識？
+│     4. 輸出會直接影響子專案原始碼？
+│
+├── 全部「否」→ Simple 路徑
+│     → 填寫 Skill Brief（templates/SKILL-BRIEF-TEMPLATE.md）
+│     → 直接建立 SKILL.md（無需 XSPEC）
+│
+└── 任一「是」→ Complex 路徑
+      → 先建立 XSPEC → 執行 /sdd
+      → XSPEC Approved 後回到此處
+
+棄用 Skill？
+  → 在 SKILL.md frontmatter 加入：
+      status: deprecated
+      deprecated_at: YYYY-MM-DD
+      deprecated_reason: "..."
+      superseded_by: "/new-skill"   (若適用)
+  → 在 SKILL-CANDIDATES.md 標記為已封存
+```
+
+## 擺放位置決策
+
+建立 SKILL.md 前，先決定它該放在哪裡：
+
+| 條件 | 擺放位置 |
+|------|----------|
+| 步驟引用專案特定路徑（如 TECH-RADAR.md、DEC-*.md） | 專案：`{project}/.claude/skills/` |
+| 步驟為通用流程（無專案特定路徑） | UDS：`skills/{name}/` + zh-TW locale |
+
+## 工作流程
+
+### Step 1 — 描述流程
+
+捕捉重複的步驟序列：
+- 哪些步驟？依什麼順序？
+- 目前手動執行過幾次？
+- 觸及哪些工具或檔案？
+
+### Step 2 — 更新 SKILL-CANDIDATES.md
+
+打開專案的 `SKILL-CANDIDATES.md`（首次請從 `templates/SKILL-CANDIDATES.md` 複製）：
+- 尚未記錄 → 新增一列，填入當前次數
+- 已記錄 → 增加次數
+- 次數達 3 → 標記 trigger ✅，繼續執行
+
+### Step 3 — 選擇路徑（Simple / Complex / Delta）
+
+回答 4 個判斷問題，決定：Simple、Complex 或 Delta。
+
+### Step 4a — Simple：填寫 Skill Brief
+
+使用 `templates/SKILL-BRIEF-TEMPLATE.md`：
+- 觸發情境（何時會用到？）
+- 核心步驟（3 ~ 7 個，有順序）
+- 驗收條件（2 ~ 3 條）
+- 範圍外（明確邊界）
+
+### Step 4b — Complex：建立 XSPEC
+
+執行 `/sdd` 建立 XSPEC。XSPEC Approved 後回到 Step 5。
+
+### Step 4c — Delta：識別變更範圍
+
+識別現有 SKILL.md 中哪些區段需要變更。
+在檔尾加入 `## MODIFIED Requirements` 或 `## ADDED Requirements`。
+
+### Step 5 — 建立 / 更新 SKILL.md
+
+依 Brief 或 XSPEC 生成 SKILL.md：
+- 確認 frontmatter：`name`、`scope`、`description`、`allowed-tools`
+- **description 格式規則**（`scope: universal` 或 `uds-specific` 時強制）：
+  - 必須以 `[UDS]` 開頭
+  - 第一行使用**繁體中文**描述用途
+  - 單行寫法：`description: "[UDS] 繁體中文說明"`
+  - 多行寫法（含 Use when / Keywords）：`description: |\n  [UDS] 繁體中文說明\n  Use when: ...`
+  - **禁止**：`description: "\"[UDS] ..."`（多餘引號會讓 description 顯示空白）
+- UDS 通用 Skill：同步建立 zh-TW locale 版本
+- 專案 Skill：放在 `{project}/.claude/skills/{name}/SKILL.md`
+
+**description 快速驗證（寫完即執行）**：
+```bash
+bash cross-project/validate-skills.sh
+# → 0 ❌ 錯誤才能繼續
+```
+
+### Step 6 — 更新 SKILL-CANDIDATES.md
+
+將候選列標記為：trigger ✅、Skill 欄位填寫完成。
+
+### Step 7 — Commit
+
+```
+feat(skills): Add /{skill-name} skill. 新增 /{skill-name} Skill。
+
+{English description, 1-2 lines}
+
+{中文描述，1-2 行}
+
+Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
+```
+
+## 輸出檢查清單
+
+完成所有步驟後，請確認：
+
+- [ ] `SKILL-CANDIDATES.md` 已更新（trigger ✅、Skill 名稱已填）
+- [ ] `SKILL.md` 已建立並有完整 frontmatter（`name` / `scope` / `description` / `allowed-tools`）
+- [ ] **description 格式**（`universal` / `uds-specific` scope 必填）：
+  - [ ] 第一行以 `[UDS]` 開頭（`"[UDS] 繁體中文..."` 格式）
+  - [ ] 使用繁體中文，非純英文
+  - [ ] 無多餘外層引號（避免 `"\"[UDS]..."` 格式）
+- [ ] `bash cross-project/validate-skills.sh` → **0 ❌ 錯誤**
+- [ ] Simple 路徑：Skill Brief 已引用或保留
+- [ ] Complex 路徑：XSPEC ID 已記錄在 SKILL.md header comment
+- [ ] UDS skill：已建立 zh-TW locale 檔案
+- [ ] 棄用：frontmatter 含 `status: deprecated`
+- [ ] git commit 已完成
+
+## 參考
+
+- Skill Brief 模板：[templates/SKILL-BRIEF-TEMPLATE.md](../../../../templates/SKILL-BRIEF-TEMPLATE.md)
+- 候選追蹤：[templates/SKILL-CANDIDATES.md](../../../../templates/SKILL-CANDIDATES.md)（請複製到專案）
+- ADR 標準：[core/adr-standards.md](../../../../core/adr-standards.md)

package/bundled/locales/zh-TW/skills/spec-derivation/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: spec-derive
+source: ../../../../skills/spec-derivation/SKILL.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-05-28
+scope: partial
+description: "[UDS] 從規格衍生 BDD 場景、TDD 骨架或 ATDD 表格"
+allowed-tools: Read, Write, Grep, Glob
+argument-hint: "[all|bdd|tdd|it|e2e|atdd] <spec-file>"
+prerequisites: ["spec-approved"]
+disable-model-invocation: true
+---
+
+# 正向推演
+
+> **語言**: [English](../../../../skills/spec-derivation/SKILL.md) | 繁體中文
+
+從已批准的 SDD 規格生成衍生工件（BDD 場景、TDD 骨架、ATDD 表格）。
+
+## 子命令
+
+| 子命令 | 說明 | 輸出 |
+|--------|------|------|
+| `all` | 完整推演管線（BDD + TDD + IT + E2E + ATDD + Contracts） | `.feature` + `.test.*` + `.it.test.*` + `.e2e.test.*` + `.md` + `.json` |
+| `bdd` | 僅生成 BDD 場景 | `.feature` |
+| `tdd` | 僅生成 TDD 骨架 | `.test.*` |
+| `it` | 生成整合測試骨架 | `.it.test.*` |
+| `e2e` | 生成 E2E 測試骨架 | `.e2e.test.*` |
+| `atdd` | 生成 ATDD 測試表格 | `.md`（Markdown 表格） |
+
+## 工作流程
+
+1. **讀取 Spec** — 分析輸入的 `SPEC-XXX.md` 檔案
+2. **抽取 AC** — 解析所有驗收條件
+3. **生成工件** — 建立 BDD / TDD / ATDD 輸出
+4. **驗證** — 確認 AC 與生成項目為一對一對應
+
+## 防幻覺規則
+
+| 規則 | 說明 |
+|------|------|
+| **1:1 對應** | 每個 AC 對應一個測試 / 場景 |
+| **追溯性** | 所有工件都引用 Spec ID 與 AC ID |
+| **不發明** | 不新增規格外的場景 |
+
+## 產生工件標籤
+
+| 標籤 | 含義 |
+|------|------|
+| `[Source]` | 直接來自規格的內容 |
+| `[Derived]` | 從來源轉換而來 |
+| `[Generated]` | AI 生成的結構 |
+| `[TODO]` | 需人工實作 |
+
+## 使用方式
+
+```
+/derive all specs/SPEC-001.md           - 完整推演管線
+/derive bdd specs/SPEC-001.md           - 僅推演 BDD 場景
+/derive tdd specs/SPEC-001.md           - 僅推演 TDD 骨架
+/derive it specs/SPEC-001.md            - 推演整合測試骨架
+/derive e2e specs/SPEC-001.md           - 推演 E2E 測試骨架
+/derive atdd specs/SPEC-001.md          - 推演 ATDD 表格
+```
+
+## 下一步引導
+
+`/derive` 完成後，AI 助手應建議：
+
+> **測試工件已產生。建議下一步：**
+> - 執行 `/tdd` 開始紅綠重構循環 ⭐ **推薦**
+> - 執行 `/bdd` 細化 Gherkin 場景
+> - 檢查產生的 `[TODO]` 標記並補齊實作
+
+## 參考
+
+- 詳細指南：[guide.md](./guide.md)
+- 核心標準：[forward-derivation-standards.md](../../../../core/forward-derivation-standards.md)
+
+## AI 代理行為
+
+> 完整的 AI 行為定義請參閱對應的命令文件：[`/derive`](../../../../skills/commands/derive.md#ai-agent-behavior--ai-代理行為)

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

@@ -0,0 +1,149 @@
+---
+name: sweep
+source: ../../../../skills/sweep/SKILL.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-05-28
+scope: universal
+description: |
+  [UDS] 掃描程式庫的除錯殘留與程式碼品質問題；可自動修正安全模式。
+  Use when: before committing, during PR review, or periodic codebase cleanup.
+  Keywords: sweep, debug cleanup, console.log, debugger, TODO, ts-any, code quality, 掃描, 清理.
+allowed-tools: Read, Grep, Glob, Bash(find:*), Edit, Write
+argument-hint: "[--fix] [--report] [--path <dir>] [--exclude <pattern>]"
+---
+
+# 掃碼助手
+
+> **語言**: [English](../../../../skills/sweep/SKILL.md) | 繁體中文
+
+掃描程式庫的除錯殘留、程式碼品質問題與技術債標記。
+可選擇性自動修正安全模式（console.log、debugger 等語句）。
+
+---
+
+## 掃描模式
+
+| Pattern ID | 名稱 | 可自動修正 | 說明 |
+|------------|------|-----------|------|
+| `console-log` | console.log / console.debug / console.trace | ✅ 是 | 留在正式環境的除錯輸出 |
+| `debugger` | debugger 語句 | ✅ 是 | 留在程式碼中的中斷點 |
+| `todo-fixme` | TODO / FIXME / HACK / XXX | ❌ 僅回報 | 技術債標記 |
+| `ts-any` | TypeScript `any` 型別 | ❌ 僅回報 | 型別安全違規 |
+
+---
+
+## 使用方式
+
+```bash
+/sweep                        # 掃描目前目錄，回報發現
+/sweep --fix                  # 掃描並自動修正可修復項目
+/sweep --report               # 掃描並將報告寫入 .uds/sweep-report.json
+/sweep --path src/            # 掃描指定目錄
+/sweep --exclude "**/*.test.ts"  # 排除模式（glob）
+```
+
+---
+
+## 執行工作流程
+
+### Step 1：搜尋檔案
+使用 Glob tool 找出目標路徑下所有原始碼檔案。
+預設排除：`node_modules/`、`dist/`、`.git/`、`*.min.js`、`coverage/`。
+
+### Step 2：逐 Pattern 掃描
+對每個 pattern 使用 Grep 在所有檔案中尋找比對結果。
+彙整發現：`{ file, line, column, pattern_id, label, fixable, content }`。
+
+### Step 3：回報發現
+輸出結構化摘要：
+```
+📊 掃描結果
+─────────────────────────────────────
+console-log:   12 筆  （可自動修正）
+debugger:       2 筆  （可自動修正）
+todo-fixme:    28 筆  （僅回報）
+ts-any:         5 筆  （僅回報）
+─────────────────────────────────────
+合計：47 筆  |  可修正：14 筆
+```
+
+### Step 4：HITL 閘門（--fix 且發現數 > 20）
+若設定 `--fix` **且**可修正發現總數超過 20：
+**暫停並要求使用者明確確認**才套用修正。
+顯示將被修改的檔案清單。
+
+### Step 5：套用修正（確認 --fix 後）
+對每筆可修正發現：
+- `console-log`：若該行僅含 console 語句則刪除該行
+- `debugger`：若該行僅含 debugger 語句則刪除該行
+
+使用 Edit tool 逐檔套用變更。
+回報：「已修正 N 筆，影響 M 個檔案。」
+
+### Step 6：儲存報告（--report）
+將發現寫入 `.uds/sweep-report.json`：
+```json
+{
+  "timestamp": "<ISO8601>",
+  "total_findings": 47,
+  "fixable": 14,
+  "fixed": 14,
+  "findings_by_pattern": { "console-log": 12, "debugger": 2, "todo-fixme": 28, "ts-any": 5 },
+  "files_modified": ["src/auth.ts", "src/utils.ts"]
+}
+```
+
+---
+
+## 設定
+
+透過 `uds.project.yaml` 設定：
+
+```yaml
+sweep:
+  default_path: "src/"
+  exclude_patterns:
+    - "**/*.test.ts"
+    - "**/*.spec.ts"
+    - "**/fixtures/**"
+  hitl_threshold: 20       # 可修正項目超過此值時需確認
+  patterns:
+    enabled:
+      - console-log
+      - debugger
+      - todo-fixme
+      - ts-any
+```
+
+---
+
+## 下一步引導
+
+`/sweep` 完成後建議：
+
+> - 執行 `/checkin` 在提交前驗證整體程式碼品質
+> - 執行 `/review` 審查清理後的變更
+> - 執行 `/commit` 提交修正
+
+---
+
+## 相關標準
+
+- [Checkin Standards](../../../../.standards/checkin-standards.ai.yaml) — Pre-commit 品質閘門
+- [Code Review](../code-review-assistant/SKILL.md) — 程式碼審查助手
+- [Testing Guide](../testing-guide/SKILL.md) — 測試標準
+
+---
+
+## 版本歷程
+
+| 版本 | 日期 | 變更 |
+|------|------|------|
+| 1.0.0 | 2026-04-28 | 初始版本 — XSPEC-097 Phase 1（從上游遷移） |
+
+---
+
+## 授權
+
+本 Skill 採用 [MIT License](https://opensource.org/licenses/MIT) 與 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 雙重授權發布。

package/bundled/skills/adr-assistant/SKILL.md

@@ -4,7 +4,7 @@ scope: universal
 description: |
   [UDS] Create, manage, and track Architecture Decision Records (ADR).
   Use when: architecture decisions, technology choices, design trade-offs, pattern selection.
-  Keywords: ADR, architecture decision, decision record, trade-off, 架構決策, 決策記錄.
+  Keywords: ADR, architecture decision, decision record, trade-off.
 allowed-tools: Read, Write, Glob, Grep
 argument-hint: "[create | list | supersede ADR-NNN | 決策主題]"
 ---

package/bundled/skills/ai-collaboration-standards/SKILL.md

@@ -4,7 +4,7 @@ scope: universal
 description: |
   Prevent AI hallucination and ensure evidence-based responses when analyzing code or making suggestions.
   Use when: analyzing code, making recommendations, providing options, or when user asks about confidence/certainty.
-  Keywords: certainty, assumption, inference, evidence, source, 確定性, 推測, 假設, 來源, 證據.
+  Keywords: certainty, assumption, inference, evidence, source.
 ---
 
 # AI Collaboration Standards

package/bundled/skills/ai-friendly-architecture/SKILL.md

@@ -4,7 +4,7 @@ scope: uds-specific
 description: |
   Design AI-friendly architecture with explicit patterns, layered documentation, and semantic boundaries.
   Use when: structuring projects for AI collaboration, optimizing codebase for AI analysis, setting up AI context.
-  Keywords: architecture, AI-friendly, context, modules, documentation layers, .ai-context.yaml, 架構, AI 友善, 上下文.
+  Keywords: architecture, AI-friendly, context, modules, documentation layers, .ai-context.yaml.
 ---
 
 # AI-Friendly Architecture Guide

package/bundled/skills/ai-instruction-standards/SKILL.md

@@ -4,7 +4,7 @@ scope: partial
 description: |
   Create and maintain AI instruction files (CLAUDE.md, AGENTS.md, .cursor/rules/, etc.) with proper structure.
   Use when: creating AI instruction files, separating universal vs project-specific rules, configuring AI tools.
-  Keywords: CLAUDE.md, AGENTS.md, cursorrules, windsurfrules, clinerules, AI instructions, system prompt, 指令檔案, AI 設定.
+  Keywords: CLAUDE.md, AGENTS.md, cursorrules, windsurfrules, clinerules, AI instructions, system prompt.
 ---
 
 # AI Instruction File Standards Guide

package/bundled/skills/api-design-assistant/SKILL.md

@@ -4,7 +4,7 @@ scope: universal
 description: |
   Guide API design following REST, GraphQL, and gRPC best practices.
   Use when: designing APIs, reviewing endpoints, API versioning decisions.
-  Keywords: API, REST, GraphQL, gRPC, endpoint, versioning, 介面設計.
+  Keywords: API, REST, GraphQL, gRPC, endpoint, versioning.
 allowed-tools: Read, Grep, Glob
 argument-hint: "[API endpoint or module | API 端點或模組]"
 ---

package/bundled/skills/audit-assistant/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: audit
 scope: universal
-description: "[UDS] UDS Health & Feedback System | UDS 健康檢查與回饋系統"
+description: "[UDS] UDS Health & Feedback System"
 allowed-tools: Read, Grep, Glob, Bash(git log, uds audit)
 argument-hint: "[--health | --patterns | --friction | --report]"
 disable-model-invocation: true

package/bundled/skills/ci-cd-assistant/SKILL.md

@@ -4,7 +4,7 @@ scope: universal
 description: |
   Guide CI/CD pipeline design, configuration, and optimization.
   Use when: setting up pipelines, optimizing build times, configuring deployment stages.
-  Keywords: CI/CD, pipeline, GitHub Actions, deployment, build, 持續整合, 持續部署.
+  Keywords: CI/CD, pipeline, GitHub Actions, deployment, build.
 allowed-tools: Read, Grep, Glob
 argument-hint: "[pipeline config or stage | Pipeline 配置或階段]"
 ---

package/bundled/skills/contract-test-assistant/SKILL.md

@@ -4,7 +4,7 @@ scope: universal
 description: |
   [UDS] Guide contract testing strategy for APIs and microservices.
   Use when: API contracts, microservices, consumer-driven testing, provider verification.
-  Keywords: contract test, Pact, OpenAPI, consumer-driven, provider, 合約測試, API 合約.
+  Keywords: contract test, Pact, OpenAPI, consumer-driven, provider.
 allowed-tools: Read, Write, Glob, Grep
 argument-hint: "[verify | consumer | provider | 策略選擇]"
 ---

package/bundled/skills/database-assistant/SKILL.md

@@ -4,7 +4,7 @@ scope: universal
 description: |
   Guide database design, migration, and query optimization.
   Use when: schema design, migration planning, query optimization, index strategy.
-  Keywords: database, schema, migration, SQL, index, query, 資料庫, 遷移, 查詢.
+  Keywords: database, schema, migration, SQL, index, query.
 allowed-tools: Read, Grep, Glob
 argument-hint: "[schema or migration to review | 要審查的 schema 或遷移]"
 ---

package/bundled/skills/deploy-assistant/SKILL.md

@@ -4,7 +4,7 @@ scope: universal
 description: |
   Guide reliable deployments without CI/CD platforms (GitHub Actions / GitLab CI).
   Use when: deploying to VPS, air-gapped servers, or environments without CI/CD infrastructure.
-  Keywords: deployment, no-cicd, shell script, blue-green, smoke test, rollback, 無CI/CD, 部署.
+  Keywords: deployment, no-cicd, shell script, blue-green, smoke test, rollback.
 allowed-tools: Read, Bash(cat VERSION:*), Bash(git describe:*), Bash(which nginx:*), Bash(which rsync:*)
 argument-hint: "[project type | 專案類型: node/python/docker/go]"
 ---

package/bundled/skills/documentation-guide/SKILL.md

@@ -4,7 +4,7 @@ scope: universal
 description: |
   Guide documentation structure, content requirements, and project documentation best practices.
   Use when: creating README, documentation, docs folder, project setup, technical docs.
-  Keywords: README, docs, documentation, CONTRIBUTING, CHANGELOG, ARCHITECTURE, API docs, 文件, 說明文件, 技術文件.
+  Keywords: README, docs, documentation, CONTRIBUTING, CHANGELOG, ARCHITECTURE, API docs.
 ---
 
 # Documentation Guide

package/bundled/skills/error-code-guide/SKILL.md

@@ -4,7 +4,7 @@ scope: universal
 description: |
   Design consistent error codes following the PREFIX_CATEGORY_NUMBER format.
   Use when: defining error codes, creating error handling, designing APIs.
-  Keywords: error code, error handling, error format, API errors, 錯誤碼, 錯誤處理.
+  Keywords: error code, error handling, error format, API errors.
 ---
 
 # Error Code Guide

package/bundled/skills/git-workflow-guide/SKILL.md

@@ -4,7 +4,7 @@ scope: universal
 description: |
   Guide Git branching strategies, branch naming, and merge operations.
   Use when: creating branches, merging, pull requests, Git workflow questions.
-  Keywords: branch, merge, PR, pull request, GitFlow, GitHub Flow, 分支, 合併, 工作流程.
+  Keywords: branch, merge, PR, pull request, GitFlow, GitHub Flow.
 ---
 
 # Git Workflow Guide

package/bundled/skills/incident-response-assistant/SKILL.md

@@ -4,7 +4,7 @@ scope: universal
 description: |
   Guide incident response, root cause analysis, and post-mortem documentation.
   Use when: production incident, outage response, post-mortem writing, RCA.
-  Keywords: incident, outage, post-mortem, RCA, root cause, 事故, 故障, 根因分析.
+  Keywords: incident, outage, post-mortem, RCA, root cause.
 allowed-tools: Read, Write, Grep, Glob
 argument-hint: "[incident description or severity | 事故描述或嚴重程度]"
 ---

package/bundled/skills/journey-test-assistant/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: journey-test-assistant
 scope: partial
-description: "[UDS] 從專案描述生成連貫使用者旅程測試計畫（TESTPLAN）與 E2E 骨架"
+description: "[UDS] Generate coherent user journey test plans (TESTPLAN) and E2E skeletons from project description."
 allowed-tools: Read, Write, Grep, Glob
 argument-hint: "[project description | --analyze | --archetype A1|A2|A3]"
 status: stable

package/bundled/skills/knowledge-graph/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: knowledge-graph
+scope: partial
+description: "[UDS] Trace spec/decision/code impact chains via a knowledge graph (engine or Markdown fallback)"
+allowed-tools: Read, Glob, Grep, Bash(curl:*)
+argument-hint: "[artifact id, e.g. XSPEC-205 | 產物 id]"
+---
+
+# Knowledge Graph | 知識圖
+
+> **Language**: English | [繁體中文](../../locales/zh-TW/skills/knowledge-graph/SKILL.md)
+
+Answer structural questions across specs, decisions, and code — *"what is the full impact chain of XSPEC-205?"* — using the [Knowledge Graph Memory](../../core/knowledge-graph-memory.md) relationship schema. Works with or without a graph engine.
+
+回答橫跨規格、決策與程式碼的結構性問題——*「XSPEC-205 的完整影響鏈是什麼？」*——依據[知識圖記憶標準](../../core/knowledge-graph-memory.md)的關係 schema。有無圖引擎皆可運作。
+
+> **Implements**: XSPEC-237 Phase 5 — knowledge-graph skill (CodeSage opt-in)
+
+## Mode Selection | 模式選擇
+
+Detect which mode to use **before** answering:
+
+| Condition | Mode |
+|-----------|------|
+| `CODESAGE_URL` set, or a local graph engine responds on `/health` | Service mode (engine) |
+| Otherwise | Degraded mode (Markdown) |
+
+## Workflow | 工作流程
+
+1. **Resolve the target** — normalise the argument to a canonical id (`XSPEC-205`, `DEC-062`, a function name).
+2. **Choose mode** — probe for a graph engine (service) else fall back (degraded).
+3. **Service mode (AC-5b)** — issue a single multi-hop query and present the returned chain, including cross-domain links (code → spec → decision):
+   ```bash
+   curl -s -X POST "$CODESAGE_URL/graph/impact-analysis" \
+     -H 'content-type: application/json' \
+     -d '{"nodeId":"XSPEC-205","maxHops":3}'
+   ```
+4. **Degraded mode (AC-5a)** — with no engine, read the target document, follow its `impacts`/`impacted_by`/`supersedes`/`related` front-matter and inline `[[ref]]` links by reading the linked files, and assemble the chain manually (bounded by reading depth).
+5. **Present the chain** — list the connected Specs and Decisions, the edge type for each hop, and (if present) each node's `confidence`, highest first.
+6. **State the mode used** — always say whether the answer came from the engine or Markdown fallback, so completeness is clear.
+
+## Relationship Schema | 關係 schema
+
+See [knowledge-graph-memory](../../core/knowledge-graph-memory.md). Front-matter fields: `related`, `impacts`, `impacted_by`, `supersedes`, `implements`. Edge derivation: Decision `impacts` Spec → IMPACTS; Decision `supersedes` Decision → SUPERSEDES.
+
+關係欄位與邊推導見[知識圖記憶標準](../../core/knowledge-graph-memory.md)。
+
+## Next Steps Guidance | 下一步引導
+
+- If degraded mode hit a reading-depth limit, tell the user a graph engine (e.g. CodeSage) would give a complete chain, and how to set `CODESAGE_URL`.
+- If a referenced id was not found, surface it as a dangling reference to fix.
+- Offer to add missing `impacts`/`impacted_by` front-matter to the documents you traversed.
+
+## Reference | 參考
+
+- Standard: [core/knowledge-graph-memory.md](../../core/knowledge-graph-memory.md)
+- Engine (opt-in): [CodeSage](https://github.com/AsiaOstrich/CodeSage) — `@asiaostrich/codesage`
+- Detailed guide: [guide.md](guide.md)