---
name: custom-skills-doc-writer
description: |
  依讀者任務與可驗證主線撰寫、重構及整理技術文件，並依專案慣例處理文件類型、路徑、檔名、frontmatter、索引與生命週期。技術文件另保護中英混合內容中的事實、命令、路徑與識別字，英文說明文字採 ASD-STE100 大原則；使用者同時提供合法標準 PDF 與本機檢查器時可自動輔助檢查。只要使用者要新增或實質改寫計畫、調查、分析、研究、進度、指南、維運手冊、教學、參考資料、原理解釋、決策、事件、會議、變更日誌或規範，就應使用本技能；整理 docs 目錄與主題索引時也適用。單純翻譯、一小段文字潤飾、只改程式碼或只查一個事實時不要使用。
---

# Document Writer

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

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

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

## 使用方式

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

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

| type | variant | 用途 |
| --- | --- | --- |
| `plan` | `general`、`feature`、`refactoring`、`migration`、`rfc` | 規劃工作或提出方案 |
| `report` | `investigation`、`analysis`、`status` | 保存調查、分析或進度結果 |
| `research` | 無 | 整理外部證據、可能性與未知 |
| `guide` | 無 | 完成一個特定目標 |
| `runbook` | 無 | 安全重複執行可能改變系統的操作 |
| `tutorial` | 無 | 透過一條可成功完成的路徑學會能力 |
| `reference` | 無 | 精確查找欄位、介面、限制或定義 |
| `explanation` | 無 | 理解原理、原因、關係與取捨 |
| `record` | `meeting`、`incident`、`decision`、`changelog` | 保存事實、事件、決定或變更 |
| `standard` | 無 | 定義規則、例外與檢查方式 |

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

## 第一階段：調查

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

整理四類資訊：

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

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

## 第二階段：寫作小卡

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

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

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

## 第三階段：組裝文件

### 先用最小骨架

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

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

### 依答案順序寫作

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

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

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

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

正式技術文件，尤其是中英混合內容，讀取 [language-and-fact-check.md](references/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](references/review-checklist.md) 分關檢查，不把所有問題混在一次 pass：

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

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

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

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

## 第六階段：發布與維護

專案慣例優先。需要判斷知識庫位置時讀取 [knowledge-base-organization.md](references/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／檢查器路徑無效、工具失敗或輸出無法判讀。
- 新文件會建立第二套任務狀態、正式規格或重複真相。
- 必須批次搬移歷史文件或修改無關文件才能套用新結構。

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

## 資源索引

| 資源 | 何時讀取 |
| --- | --- |
| [document-types.md](references/document-types.md) | 選定文件類型後，讀對應章節 |
| [content-blocks.md](references/content-blocks.md) | 文件需要證據、方案、安全、相容性或任務資訊時 |
| [language-and-fact-check.md](references/language-and-fact-check.md) | 正式技術文件、中英混合內容或使用選用 ASD 檢查器時 |
| [review-checklist.md](references/review-checklist.md) | 草稿完成後 |
| [knowledge-base-organization.md](references/knowledge-base-organization.md) | 需要決定路徑、索引、主題或生命週期時 |