Explain

/explain：互動式視覺解釋

本 skill 產出完整前因後果＋視覺化／互動式的解釋。

核心原則：先診斷這次主題是什麼形狀、讀者是誰，再對照下面 Tier C 選方法。 不要把上一次的樣板原封套上去。下面分三層：A 永遠做、B 幾乎永遠做（按複雜度縮放）、C 看主題特徵才選。

交付方式：起一個本機 HTTP server、把網址給使用者（HTML 是 single-file，能直接用瀏覽器開也行）。

Tier A：永遠做（交付品質，跟主題無關）

• 對 ground truth 驗證：每個 claim 先自己 grep／Read／查證過再畫。錯的漂亮圖比沒圖更糟。
• 截圖反向驗證：交付前用 headless Chrome（chrome-devtools）開頁、take_screenshot 看實際 render，破版／錯字／em-dash 當場抓。不能只看檔案存在。
• single-file、self-contained：CSS／JS 全內嵌，零外部 CDN／lib（離線載不到會破版）。
• serve 成本機 HTTP server、給 URL。
• 跟著使用者的語言輸出：英文只留代碼識別字（class／method／檔名）和標準縮寫（MCP／API／SQLite…）。
• 不用破折號（U+2014 em-dash）：rendered 文字掃到零（改用一般標點斷句）。
• 不編造：不確定的標出來。

Tier B：幾乎永遠的方法（但按主題複雜度縮放）

1. 概念先行（DDD 共通語彙）：先建立共通詞彙再講細節。jargon 重的主題→放一塊分組詞彙表（中文名（English）＋1-2 句定義）擺在任何圖之前；簡單主題→一兩句帶過。這同時是「術語一次講白」的地方。
2. 深度分層：表面簡單、深度收在底下。注意「分層 ≠ 一定多頁」：

• 大主題（部件多）→ 分層多頁（top-level 總覽連各 submodule detail、互相 hyperlink、設計系統一致；先做 top-level 當樣板確認，OK 再用同套生其餘）。
• 小主題 → 單頁內用 drawer／section 分層即可。

Tier C：看主題特徵才選（先診斷、再對照）

> 視覺類的選擇大多在這層。先重判一次主題特徵，別套上一次的樣板。

| 問這個 | 是 → 用 | 否／反面 → 改用 | |---|---|---| | 主題是程式碼、有 repo + commit？ | file:line 永久連結（一個 helper 加前綴 ///blob//#L）、commit 快照戳記、對源碼驗證 | 商業決策／事故時間線／市場分析：沒 repo 可連，這些全跳過 | | 主題本質是「實體」（有身分的物件／模組／服務＋關係），還是「流程／時序」？ | 實體形 → 非正規 UML class diagram 當主視角，sequence 當次視角 | 流程／時序形 → flow／sequence／timeline 當主視角（別預設，先判） | | 體量大、部件多，還是小、少？ | 大 → 寬白板（full-bleed）、box 拉開、收合 tile | 小 → 單頁攤開、box 直接全顯示、免白板 | | 每個部件細節深，還是一句話講完？ | 深 → 漸進揭示：tile 只放名稱＋短標籤，點開右側 drawer 看完整內容 | 淺 → 細節直接標在圖上、不用 drawer | | 關係圖很密，還是疏？ | 密 → 關係線預設淡灰、hover／選中才高亮、其餘變淡 | 疏 → 全部畫實線就好 | | 讀者技術、要自己 verify，還是非技術？ | 技術 → file:line 連結、技術深度、可跳源碼 | 非技術 → 砍 file:line、用類比、簡化詞彙 | | 互動元素點得下去嗎？ | 是 → 在圖標題附近明說「點卡片看詳情」，別讓人猜 | 純靜態 → 不需要 |

步驟

1. 整理＋診斷：把素材寫成前因後果（背景 → 為什麼 → 證據（引實際檔案／行）→ 選項／結論），先對 ground truth 驗證；同時跑一遍 Tier C 的診斷，決定這次用哪些方法。
2. 派 subagent 生 HTML（Agent tool、general-purpose、opus）：把 Tier A ＋ B ＋（診斷後選定的）C 寫進 brief，要它對照 source 驗證每個 claim 再畫，寫到 /tmp/explainers/.html（先建目錄）。多頁時先 top-level、再用它當樣板生 detail（reuse 同一份 CSS／JS、只換資料）。
3. 截圖反向驗證（Tier A）。
4. Serve（背景）：

``bash cd /tmp/explainers && python3 -m http.server 8088 ` runinbackground: true`。port 8088 被佔就換。多頁共用同一 server（serve 整個目錄）；已在跑就重用、別重起。

1. 給 URL：確認頁面可達後，把網址給使用者 http://localhost:8088/.html（多頁時入口給 top-level）。若使用者從別台機器看，換成那台 server 可達的位址。
2. server 背景跑，看完可關（TaskStop 或 kill）。

別做

• 別無腦套樣板：先跑 Tier C 診斷，主題不同方法就不同。
• 沒 GUI 的環境別用 open（改 serve ＋ 給 URL）。
• 別生依賴外部 CDN／lib 的 HTML。
• 別編造資料；不確定的標出來。
• 別用破折號。

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: j0214ack
• Source: j0214ack/claude-skills-better-human-decisions
• License: MIT

Install and usage instructions live in the source repository linked above.