Dry-run Guide — Skill 發布前語意層驗收
本文件定義 compositional-writing Skill 的 Phase 2 語意層驗收流程。Phase 1 是自動化形式掃描（portability-check.sh），Phase 2 是語意層驗收——驗證一個不熟悉本框架的新使用者，只讀 SKILL.md 和對應 reference 後，能否獨立套用寫作方法論。
Phase 2 的核心問題：形式合規不代表內容可理解。本流程解答「Skill 內容品質是否足以讓陌生讀者自立運作」。
適用時機
| 觸發情境 | 說明 |
|---|---|
| Skill 發布至 marketplace 前 | 必須執行，作為最終品質門 |
| 新增或大幅修改 reference 後 | 必須針對變動的 reference 跑對應場景 |
| meta-metrics.md 顯示 M2 疑慮 | 以本流程做進一步驗證 |
| 定期健檢（每季） | 建議執行，確認內容未因周邊框架演進而失效 |
前置條件
執行 Phase 2 前，以下條件必須已成立：
- Phase 1 通過：
./scripts/portability-check.shexit 0 - SKILL.md 和所有核心 reference 均已完成（writing-code-comments / writing-documents / writing-logs / writing-prompts / writing-articles / translation-review / designing-fields）
- meta-metrics.md 已完成（M1-M2 量測方式已定義）
測試人員要求
Phase 2 測試人員必須符合：
| 要求 | 說明 |
|---|---|
| 對本框架陌生 | 未曾閱讀過 .claude/ 目錄任何框架規則 |
| 有基礎寫作能力 | 能寫 markdown，有寫程式碼或文件的基本經驗 |
| 可取用的資料 | 僅限 SKILL.md + 指定 reference（不可額外 Google、詢問他人） |
若找不到完全陌生的測試人員，可使用「情境隔離法」：測試者在全新 session 中（不帶任何框架記憶），只閱讀指定文件後完成場景。
測試場景（3 個基本場景）
每個場景設計原則：
- 輸入：只給測試人員 SKILL.md + 1 個對應 reference
- 任務：測試人員獨立完成寫作任務
- 時限：每個場景 10 分鐘
場景 A：撰寫程式碼 doc comment
對應 reference：writing-code-comments.md
任務描述（給測試人員的指示）
你有一個 JavaScript 函式，功能是「驗證使用者輸入的書名是否符合格式（非空、長度 1-200 字元）」。
請只閱讀 SKILL.md 和 writing-code-comments.md，為以下函式撰寫一則 doc comment：
1function validateBookTitle(title) {
2 if (!title || title.trim().length === 0) return false;
3 if (title.trim().length > 200) return false;
4 return true;
5}輸入限制
- 可讀：SKILL.md、references/writing-code-comments.md
- 不可讀：其他任何文件
預期產出
符合以下條件的 doc comment：
- 說明業務意圖（為什麼驗證，不是程式碼在做什麼）
- 說明輸入語意和邊界條件
- 說明回傳值的含義
- 不描述實作語法
評估標準
| 評估項目 | 通過條件 |
|---|---|
| 意圖顯性 | comment 說明「為何」而非「如何」 |
| 原子化 | comment 只解釋此函式的一個職責 |
| 輸入輸出語意 | 明確說明 title 的合法格式與 false 的意義 |
| 無多餘翻譯 | 不出現「如果 title 為空則回傳 false」這類程式碼翻譯句 |
通過判定：4 項中達到 3 項以上 = 通過。
場景 B：起草技術文件段落
對應 reference：writing-documents.md
任務描述（給測試人員的指示）
你需要為一份「書庫同步錯誤處理設計」文件撰寫開頭章節（Introduction 或 Overview）。
背景資訊（只有這些）：
- 系統名稱：Readmoo 書庫管理器
- 問題：書庫同步會遇到網路中斷、資料格式不符、API 限流三種錯誤
- 讀者：接手此模組的開發者（假設有基礎 JavaScript 能力，不熟悉 Readmoo 平台）
請只閱讀 SKILL.md 和 writing-documents.md，撰寫一個 150-300 字的開頭段落，讓讀者第一眼就知道「這份文件解決什麼問題、讀它能得到什麼」。
輸入限制
- 可讀：SKILL.md、references/writing-documents.md
- 不可讀：其他任何文件
預期產出
符合以下條件的開頭段落：
- 第一句說清楚文件解決的問題（不從背景鋪陳）
- 指明讀者是誰
- 列出文件涵蓋的三種錯誤類型
- 不超過 300 字
評估標準
| 評估項目 | 通過條件 |
|---|---|
| 意圖前置 | 第一句即說明文件解決的問題，不先鋪背景 |
| 讀者定位 | 明確說明目標讀者是誰 |
| 範圍聲明 | 列出本文件涵蓋的三種錯誤類型 |
| 精簡 | 不超過 300 字、無填充詞（「在這份文件中，我們將…」） |
通過判定：4 項中達到 3 項以上 = 通過。
場景 C：設計 YAML 欄位命名
對應 reference：designing-fields.md
任務描述（給測試人員的指示）
你正在設計一份 YAML 格式的「書籍匯出任務」結構，需要包含以下資訊：
- 任務的唯一識別碼
- 任務被建立的原因（是使用者手動觸發，還是排程自動觸發）
- 任務的目標輸出格式（CSV 或 JSON）
- 任務目前的執行狀態（待執行、執行中、完成、失敗）
- 任務完成後通知的方式（email 或 webhook）
請只閱讀 SKILL.md 和 designing-fields.md，設計上述 5 個欄位的名稱與值的格式（用 YAML 示例呈現即可）。
輸入限制
- 可讀：SKILL.md、references/designing-fields.md
- 不可讀：其他任何文件
預期產出
一段 YAML 示例，每個欄位有名稱和示例值，並附一行說明「此欄位承載什麼維度的資訊」。
評估標準
| 評估項目 | 通過條件 |
|---|---|
| 欄位職責單一 | 每個欄位只描述一個維度，無複合欄位（如 trigger_and_format） |
| 名稱即提問 | 欄位名稱讀者能猜到「它在問什麼問題」 |
| 值格式一致 | 狀態類欄位使用 enum（固定可選值），不用自由文字 |
| grep 友善 | 欄位名稱無縮寫、蛇形命名（如 output_format 非 outFmt） |
通過判定：4 項中達到 3 項以上 = 通過。
通過標準（量化）
整體 Phase 2 通過條件：
| 指標 | 通過值 | 說明 |
|---|---|---|
| 場景通過率 | 100%（3/3 場景） | 任一場景未通過即整體 FAIL |
| 單場景完成時間 | 10 分鐘內 | 超時視為理解障礙，需調查根因 |
| 場景內評估項通過率 | 75% 以上（至少 3/4 項） | 低於此值視為該場景 FAIL |
通過計算式：
1Phase 2 通過 = (所有場景通過) AND (所有場景在 10 分鐘內完成)
2
3場景通過 = 評估項通過率 >= 75%評估問卷（測試後請測試人員回答）
每個場景完成後，請測試人員回答以下問題（1-5 分，5 分最高）：
| 問題 | 目的 |
|---|---|
| Q1. SKILL.md 的觸發路由表讓你清楚知道要讀哪個 reference 嗎？ | 驗證 M1 路徑設計 |
| Q2. 你讀完指定 reference 後，能獨立完成任務而不需要其他資料嗎？ | 驗證 M2 獨立理解率 |
| Q3. reference 中是否有你不理解的名詞或概念？（有請列出） | 發現就地定義缺失 |
| Q4. 如果你要把本方法論教給同事，你覺得這份文件夠完整嗎？ | 整體可遷移性 |
問卷通過標準：Q1 + Q2 平均分 >= 4 分，Q3 無未解答的名詞。
執行步驟
11. 確認前置條件：執行 ./scripts/portability-check.sh，exit 0 才繼續
22. 找到測試人員（符合「對本框架陌生」條件）
33. 依序執行場景 A → B → C，記錄每個場景的完成時間和評估項結果
44. 場景結束後請測試人員完成評估問卷
55. 計算通過率（場景 + 問卷）
66. 填寫下方結果記錄表
77. 若有場景 FAIL，記錄根因並提交修正 Ticket結果記錄表（執行後填寫）
1Phase 2 Dry-Run 結果（日期：_____ / 執行者：_____）
2
3場景結果
4
5| 場景 | 完成時間 | 評估項通過數 | 通過判定 |
6|------|---------|------------|---------|
7| A：程式碼 doc comment | ___ 分鐘 | ___/4 | PASS / FAIL |
8| B：技術文件段落 | ___ 分鐘 | ___/4 | PASS / FAIL |
9| C：YAML 欄位設計 | ___ 分鐘 | ___/4 | PASS / FAIL |
10
11問卷結果
12
13| 問題 | 分數（1-5） | 備註 |
14|------|-----------|------|
15| Q1 觸發路由清晰度 | ___ | |
16| Q2 reference 獨立理解率 | ___ | |
17| Q3 不理解的名詞 | N/A（列出：_____） | |
18| Q4 整體可遷移性 | ___ | |
19
20整體結論：PASS / FAIL
21FAIL 時的修正清單：
22- （列出需要修正的 reference 或章節）常見失敗根因與對應修正
| 症狀 | 根因 | 修正方向 |
|---|---|---|
| 測試人員完成時間 > 10 分鐘 | reference 資訊密度過高或結構不清 | 重新組織 reference，讓 TL;DR 或 Quick Reference 更突出 |
| 測試人員需要查閱第二個 reference | reference 未自包含（M2 FAIL） | 把被引用內容的精要直接寫入當前 reference |
| 評估項「意圖顯性」通過率低 | SKILL.md 對「意圖顯性」的定義不夠具體 | 在對應 reference 加入更多示例（正例 + 反例） |
| 問卷 Q3 列出未解答名詞 | 首次出現的術語缺少就地定義 | 在術語首次出現處加入一行定義（括號說明或 note block） |
| 場景 C 欄位設計評估項通過率低 | designing-fields.md 的「欄位名稱即提問」原則不夠清楚 | 在該原則下加更多反例對照（好名稱 vs 壞名稱） |
Last Updated: 2026-04-18 Version: 1.0.0