Valorvie Custom Skills Custom Skills Doc Writer

Document Writer — 統一格式文件撰寫

使用方式

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

若使用者已提供完整引數，直接載入對應模板執行。若未提供或資訊不足，透過互動引導。

引數解析

type（文件類型）與 variant（子類型）

流程

Step 1: 判斷引數來源

依以下優先順序決定 type/variant：

1. 使用者明確指定 → 直接使用，跳到 Step 3
2. 未指定但有對話脈絡 → 進入 Step 1.5 脈絡推斷
3. 無引數且無脈絡 → 進入 Step 2 互動引導

Step 1.5: 脈絡推斷（從對話內容判斷文件類型）

當使用者在對話中說「把剛才的討論寫成文件」「整理成報告」等模糊指令時，根據對話內容特徵推斷文件類型。

推斷規則 — 依對話內容的核心動詞/意圖判斷：

關鍵區分原則：

• report vs record：report 是「分析與結論」（有方法論、有證據鏈、有建議），record 是「事實紀錄」（有時間線、有出席者、有決議）
• investigation vs incident：investigation 回答「為什麼發生」，incident 回答「發生了什麼、怎麼處理」
• analysis vs decision：analysis 回答「哪個比較好」，decision 回答「我們選了什麼」

推斷後必須確認： 向使用者明確說明推斷結果並確認：

根據我們剛才的討論（分析了 XX 的根因與影響範圍），建議使用「調查報告」格式。確認嗎？

使用 AskUserQuestion 提供推斷結果作為推薦選項，同時列出其他可能選項讓使用者選擇。

Step 2: 互動引導（無脈絡時）

使用 AskUserQuestion 逐層引導：

第一層 — 文件類型：

• 計畫 (plan) — 規劃未來要做的事
• 報告 (report) — 記錄已完成的分析或進展
• 指南 (guide) — 說明如何完成某件事
• 教學 (tutorial) — 分步驟教學，含練習
• 紀錄 (record) — 記錄事件或決策
• 規範 (standard) — 定義規則與標準

第二層 — 子類型（僅 plan、report、record 需要）：

plan:

• 新功能 (feature)
• 重構 (refactoring)
• 遷移 (migration)
• 通用 (general)
• 技術提案 (rfc)

report:

• 調查報告 (investigation)
• 階段報告 (status)
• 分析報告 (analysis)

record:

• 會議紀錄 (meeting)
• 事件紀錄 (incident)
• 決策紀錄 (decision)
• 變更日誌 (changelog)

Step 3: 載入模板

根據確定的 type/variant，讀取 references/template-{type}-{variant}.md（或 references/template-{type}.md）。

Step 4: 收集文件資訊

詢問使用者必要資訊（若未在指令中提供）：

• 輸出路徑: 文件存放位置（依類型提供預設路徑，使用者可覆寫）

預設輸出路徑：

按文件類型補問必要資訊（若已在對話脈絡或指令中提供則跳過）：

Metadata 自動填入：

• title: 從檔名的標題部分自動填入
• date: 從檔名的 YYYYMMDDhh-NN 部分自動填入
• author: 從 git config 取得或留空

Step 4.5: 判斷內容來源

• 對話轉文件：對話中已有充分的技術討論內容，直接從對話萃取，掃描對話中的事實、結論、建議，對應到模板章節，不重複詢問已知資訊
• 從零撰寫：無對話脈絡或資訊不足，依 Step 4 的類型必要欄位逐項收集

Step 5: 撰寫文件

根據模板結構撰寫文件內容：

1. 填入 frontmatter metadata
2. 根據使用者提供的背景資訊，填充各章節內容
3. 若章節明確不適用於當前文件，直接刪除該章節，不留空佔位符。僅在資訊暫時不足但章節本身合理時才保留 <!-- TODO: 補充 -->
4. 若使用者提供了參考資料（如 @file），讀取後融入文件內容

Step 5.5: 品質自檢

撰寫完成後執行以下檢查：

1. frontmatter 所有必填欄位是否完整
2. 殘留的 <!-- TODO --> 是否合理（不可填的才留）
3. 表格是否有空行或格式錯誤
4. 標題層級是否符合規範（最深不超過 ####）
5. 檔名是否符合 YYYYMMDDhh-NN-標題.md 格式

Step 6: 後續建議

文件撰寫完成後，根據文件類型提示：

共通格式規範

檔名命名規則

所有產出文件統一使用以下格式：

YYYYMMDDhh-NN-標題.md

流水編判定邏輯：

1. 掃描專案目錄內所有以當日日期 YYYYMMDD 開頭的檔案
2. 取最大流水編 +1；若無則從 01 開始，YYYYMMDDhh-NN 流水編全域唯一

格式基線

• Frontmatter: 所有文件包含 YAML frontmatter（title、type、date、author、status）
• 標題層級: # 文件標題、## 主要章節、### 子章節，最深不超過 ####
• 表格: 結構化比較或清單使用 Markdown 表格
• 清單: 待辦事項使用 - [ ]，一般列表使用 -
• 程式碼: 使用 fenced code block 並標註語言
• 語言: 預設繁體中文，除非使用者指定其他語言

模板索引

所有模板位於 references/ 目錄：

擴展時只需在 references/ 新增 template-{type}-{variant}.md 並更新上方引數表。

Converted and distributed by TomeVault — claim your Tome and manage your conversions.