custom-skills-doc-writer

Document Writer

完整流程是：調查 → 寫作小卡 → 文件組裝 → 語言與事實守門 → 成稿檢查 → 發布與維護。草稿寫完不代表完成；受保護內容、路徑、連結、索引、證據界線與讀者檢查都完成才交付。

技術文件的目標不是模仿人類寫作風格，而是讓目標讀者用最低理解成本取得正確、足夠、可驗證的資訊。優先順序是：正確性 → 任務相關性 → 清晰度 → 資訊密度 → 邏輯連貫 → 一致性 → 自然度。不要為了降低 AI 可辨識度而打破固定結構、改變真實列舉數量、替換固定術語，或加入不必要的個性與不規則性。

開始前先在內部確認六個階段及各自產出，不必為了流程向使用者重述已知資訊。

使用方式

/custom-skills-doc-writer [type] [variant]

若使用者指定類型，直接採用。未指定時先從對話與現有文件推斷；只有不同選擇會改變讀者、用途、保留方式或輸出位置時才確認。

選定後讀取 document-types.md 的對應章節。不要載入或照填其他類型。

第一階段：調查

先讀取使用者要求、專案中的 AGENTS.md、CLAUDE.md、文件索引、同主題文件與直接證據。專案沒有某個入口時跳過，不要自行建立空架構。

整理四類資訊：

• 已直接確認的事實。
• 根據證據得到的推論。
• 仍未知而且會影響內容的問題。
• 本次不能修改、不能公開或不能宣稱的範圍。

AI 助理應先自己查。只有資料找不到、正式來源互相衝突，或答案需要使用者決定目標、取捨、公開範圍與授權時才提問。

第二階段：寫作小卡

在動筆前建立一張內部小卡。小卡用來決定文章，不要原封不動貼進成稿。

1. 主要讀者是誰？可以假設他已經知道什麼？
2. 他現在要完成哪件事，或回答哪個問題？
3. 讀完後應該知道、決定或做到什麼？
4. 最主要的答案、決定或行動是什麼？
5. 哪些是證據、推論與未知？
6. 哪些內容在範圍內？哪些不應放進這份文件？
7. 這是保留某個時點的結果，還是持續維護的入口？

接著列出讀者完成任務前必須回答的三到五個問題。簡單文件不必硬湊三題；超過五個主要問題時，先檢查是否混入第二種文件用途，或是否該拆成入口與細節文件。

第三階段：組裝文件

先用最小骨架

從 document-types.md 取得該類型的問題順序。標題可以配合內容改寫，重點是每一節都回答一個真實讀者問題。

需要證據分級、方案比較、安全操作、相容性或任務連結時，再讀 content-blocks.md 的對應內容。可選內容不是待填欄位；沒有證據或不影響本次讀者的內容直接省略。

依答案順序寫作

• 開頭先說文件目的、目前答案或要採取的行動，再放細節。
• 一個章節回答一個主要問題。第一段直接給答案、狀態或行動。
• 長篇正文中的每一段都應有一個主要資訊責任；找不到責任的段落應刪除或併入相關段落，責任重複的相鄰段落優先合併。
• 相鄰章節或段落若有因果、依賴、比較、時間或狀態變化，直接說明關係，不讓讀者自行推斷。
• 摘要放結論，正文放證據；不要在摘要、發現、建議與結論重複同一段內容。
• 表格只用於多個項目的固定欄位比較或精確查找。原因、過程與論證優先使用段落。
• 已有正式入口的內容用連結，不複製一份新的真相。
• 把本技能的流程、檢查與安全規則當成 Agent 內部約束；它們不自動是目標系統事實、讀者前置條件或正文內容。只有正式來源也支持，或讀者確實要執行該操作契約時，才寫進成稿。
• 資訊暫時未知但不影響結論時清楚標示；若會改變結論或操作安全，停止並詢問。

高風險內容不能因精簡而消失

操作會改變系統、資料、服務、流量、權限或費用時，必須保留目標、執行身分、影響、非目標、完整操作、前置檢查、預覽、備份、成功條件、停止點、驗證、回復與稽核紀錄。細節使用 content-blocks.md 的安全操作內容。

第四階段：語言與事實守門

正式技術文件，尤其是中英混合內容，讀取 language-and-fact-check.md。先列出不能改寫的技術字串與事實，再分別處理可改寫的中文與英文說明文字。

英文使用 ASD-STE100 的大原則，中文使用可跨語言的清楚表達原則。這些原則不等於正式符合性判定；不能因簡化而改動人物、時間、數字、命令、條件、狀態、範圍或不確定性。

先完成 plain technical prose 的規則式改寫：保留必要專業術語，其他說明優先使用普通、直接、具體的語言；能用具體動詞時，不用抽象名詞包裝動作；刪除填充、宣傳語、模糊歸因、同義詞循環、過度限定與通用結尾。

humanizer-zh-tw 是選用的自然語氣 polish，不是固定完成條件。只有可改寫的中文說明仍有明顯翻譯腔、客服腔、過度正式或不自然句法時才使用。reference、runbook、standard 與事實型 record 預設不為了「更像真人」額外改寫；若使用 humanizer，doc-writer 的精確性、固定結構、真實列舉數量、格式可掃描性、術語一致性、證據界線與安全條件一律優先。整理後重新比對技術字串與事實，最後才對成稿執行選用的機器檢查。

若使用者同時提供合法取得的 ASD-STE100 PDF 絕對路徑，以及使用者或專案明確批准的本機檢查器可執行檔絕對路徑，依參考文件的固定介面自動執行。缺少任一項時不執行機器檢查，仍完成原則式審閱。不要自行搜尋、下載或安裝 PDF、字典或檢查器。

第五階段：成稿檢查

使用者指定行數、字數、格式或必備欄位時，先把它們列為完成條件，交付前以可重現方式實際量測。超過限制時先刪除重複與無關內容；不得為了縮短而刪掉證據界線、安全條件或必備資訊。

依 review-checklist.md 分關檢查，不把所有問題混在一次 pass：

1. 目的、主線與資訊效用。
2. 段落責任與連貫。
3. 證據與行動。
4. 語言、事實與技術字串。
5. 格式與生命週期。

長篇、跨層或高風險文件完成前一關並修正後，再進下一關。短文件可合併相鄰檢查，但仍以內容正確與讀者任務優先於語氣與格式。

長篇、跨層或高風險文件再做陌生讀者試讀：挑三到五個真實問題，讓沒有對話背景的 AI 助理或真人只憑文件作答。記錄答對、答錯、靠猜或找不到，以及引用位置。

AI 試讀只能標成「AI 可理解性檢查」，不能代替真人使用結果、命令測試、程式測試、同行審查或正式批准。短小、單純查值或只有一個明確步驟的文件不啟動額外試讀。

第六階段：發布與維護

專案慣例優先。需要判斷知識庫位置時讀取 knowledge-base-organization.md。

路徑與檔名

• 依專案現有結構選擇 docs/<type>/<topic>/ 或既有位置，不為單一文件建立整套空目錄。
• 調查、階段、事件、會議、執行結果與短期計畫等時點證據使用 YYYYMMDDhh-NN-<title>.md。
• 架構、規範、索引、狀態看板、參考資料與長期操作入口使用穩定檔名。
• NN 是當天整個專案的流水編；掃描所有當日檔名後取最大值加一。

Frontmatter 與索引

新 Markdown 文件預設包含 title、type、date、author、status；專案規則不同時從專案。大型知識庫再加入實際會查找的 topic、related_topics、supersedes 或 superseded_by，不要建立沒有人維護的欄位。

新文件建立新主題、取代舊文件或讓清單難以瀏覽時，更新最近且能幫讀者找到它的索引與取代關係。不需要機械式更新每一層索引。

完成交付

回覆使用者時說明：

• 建立或修改哪些文件。
• 主要結論、使用方式或決定。
• 做過哪些格式、連結、內容與行為驗證。
• 技術文件是否執行 ASD 檢查；結果是未檢查、無提醒、有提醒或工具失敗。
• 哪些仍未知、尚未執行或需要人工確認。
• 若有操作手冊，成功後應回到哪份文件的哪個段落繼續。

停止條件

遇到以下情況先停止，不自行放大範圍：

• 讀者或文件用途無法由現有資料判定，而且不同選擇會改變內容。
• 正式來源對主要結論互相衝突，無法合理說明。
• 缺少會影響安全、公開範圍、回復或驗收的資訊。
• 使用者把機器語言檢查列為必要驗收，但 PDF／檢查器路徑無效、工具失敗或輸出無法判讀。
• 新文件會建立第二套任務狀態、正式規格或重複真相。
• 必須批次搬移歷史文件或修改無關文件才能套用新結構。

停止時說明已確認的事實、缺少什麼、可選方向和每個方向的影響，再請使用者決定。

資源索引