Comprehension Ladder

---
name: comprehend
source: ../../../../skills/comprehension-ladder/SKILL.md
source_version: 1.0.0
translation_version: 1.0.0
last_synced: 2026-10-05
source_hash: 7c69dc2bfc9f
status: current
scope: universal
description: |
  [UDS] 把一段難懂的 AI 輸出換成較好懂的形式：受控文字、Mermaid 圖、單檔 HTML 解說頁。所有形式都來自同一份大綱，所以形式會變，事實不會變。
  Use when: AI 的說明、規格或程式碼解說太密、讀的人看不出該不該核准；非專業的人必須靠它做核准；想要它的圖或離線解說頁。
  Not for: 寫新內容或加新分析——本技能只把既有的文字換形式；從原始碼產生文件——請用 /docgen；為專家讀者縮短文字——直接改寫即可。
  Keywords: comprehension ladder, explainer, controlled language, Mermaid, HTML explainer, outline, plain language, understand AI output, 理解階梯, 受控語言, 流程圖, 解說頁, 換形式不換事實.
allowed-tools: Read, Glob, Grep, Write
argument-hint: "[text or file | 原文或檔案] [rungs: 1 | 2 | 3]"
---

# 理解階梯

> **語言**: [English](../../../../skills/comprehension-ladder/SKILL.md) | 繁體中文 | [简体中文](../../../zh-CN/skills/comprehension-ladder/SKILL.md)

**版本**: 1.0.0 | **最後更新**: 2026-10-05 | **適用**: Claude Code Skills

把一段難懂的 AI 輸出換成較好懂的形式。形式會變，事實不會變。

## 目的

現在慢的不是拿到答案，而是看懂答案並判斷它。本技能幫忙這一步。它拿一份原文，最多做出三種形式，每一種叫一「階」。

本技能的文字依 [ai-response-navigation](../../core/ai-response-navigation.md) 第 12 條（受控語言）寫成。它自己也遵守自己的防護。

## 階梯

階梯正好有三階。每一階都從同一份大綱產生（見[大綱](#大綱)）。任何一階都不得在大綱之外加東西。

| 階 | 形式 | 適合 | 產出 |
|----|------|------|------|
| 1 | 受控文字 | 任何原文。永遠是第一階 | 短句或編號列，放在對話或檔案裡 |
| 2 | Mermaid 圖 | 有流程、先後順序、多個角色，或 3 個以上選項的原文 | 一個 Mermaid 程式碼區塊，外加一份畫不出來的項目文字清單 |
| 3 | 單檔 HTML 解說頁 | 需要探索或核准的讀者 | 一個可離線開啟的 `.html` 檔 |

先問使用者要哪幾階。使用者沒說，就先做第 1 階，再提議另外兩階。

沒有影片階。影片需要語音服務，而且會把原文送給第三方。

## 三條防護

這三條防護**必須**遵守。破壞任何一條的那一階，就還沒做完。不得交出去。

| 編號 | 防護 | 等級 |
|------|------|------|
| G1 | `no-new-facts`：不加原文沒有的事實 | **必須（Required）** |
| G2 | `keep-hedges`：保留每一個不確定語氣。不得把不確定的說法改成確定 | **必須（Required）** |
| G3 | `trace-and-gaps`：每一項都附「對應原文哪一段」與「沒涵蓋什麼」 | **必須（Required）** |

G2 與 [ai-response-navigation](../../core/ai-response-navigation.md) 的 12.1 條是同一條規則。這裡把它用在本技能的三階。

### G1 `no-new-facts`（必須）

每一階的每一個說法都必須來自原文。不要加原因、數字、名字、日期或「已確認」。不要加你知道、但原文沒寫的背景。

**正例**——原文寫：「訂單有時會在付款步驟失敗。」

```text
O1  訂單有時會在付款步驟失敗。
```

**反例**——同一份原文：

```text
O1  訂單會在付款步驟失敗。這也會讓退款壞掉。
```

「退款」是新增的事實。「有時」也不見了，所以 G2 同時被破壞。

### G2 `keep-hedges`（必須）

不確定語氣告訴讀者，一個說法可以信到什麼程度。例如：可能、推斷、大概、尚未確認、might、could、probably。它是資訊，不是贅字。

- 原文寫「可能」，這一階就寫「可能」。
- 圖裡也要保留。不確定的項目用虛線畫，標籤裡留下那個詞。
- HTML 裡也要保留。不確定的項目要顯示看得見的「尚未確認」標記。
- 只有在原文自己說這個說法已經驗證時，才可以拿掉不確定語氣。這時要寫出檢查了什麼。

**正例**——原文寫：「原因可能是快取留著舊的價目表。」

```text
O2  原因可能是快取留著舊的價目表。   [hedge: 可能]
```

**反例**——同一份原文：

```text
O2  原因是快取留著舊的價目表。
```

反例比較短，也比較好讀。但它與原文不符。讀的人若憑這一行核准修復，就被誤導了。

### G3 `trace-and-gaps`（必須）

每一項都帶兩個註記：

- **對應原文**：這一項出自原文的哪個位置。用段落與句子編號，或檔名與行號，再加一段 12 個詞以內的引文（中文約 20 字以內）。
- **沒涵蓋**：這一項沒說到什麼，或它證明不了什麼。原文沒有更多內容時，寫「原文沒有更多內容」。

最後一項之後，加一份清單，叫做**這份大綱沒有收的部分**。它列出原文中所有沒變成項目的部分。

**正例**

```text
O3  我們尚未在測試環境重現這個問題。
    對應原文：第 1 段第 3 句——「尚未在測試環境重現」
    沒涵蓋：為什麼沒有重現。原文沒有給理由。
```

**反例**

```text
O3  這個問題已在測試環境重現。
    對應原文：那份報告。
```

「那份報告」沒有指向某個位置。這個說法也與原文相反。而且沒有「沒涵蓋」註記。

## 大綱

大綱是唯一共用的事實來源。先做大綱，再做任何一階。不要直接從原文寫某一階。

每個大綱項目有一個編號和一個種類。

| 種類 | 意思 |
|------|------|
| `claim` | 原文提出的說法 |
| `mechanism` | 一個步驟、一個原因，或兩件事之間的關聯 |
| `uncertainty` | 原文說不知道或尚未確認的事 |
| `example` | 原文拿來說明某個說法的案例 |

每個項目寫成這個樣子：

```text
O<編號> | 種類 | 文字 | hedge: <原文的不確定用詞，或 none>
  對應原文：<位置> — 「<引文，12 個詞以內>」
  沒涵蓋：<這一項沒說到的事>
```

依原文的順序編號。編號不得重複使用。三階都用同一組編號。

## 工作流程

### 步驟 1——讀原文

讀完整份原文。原文是檔案，就讀那個檔案。讀完之前，不要開始做大綱。

### 步驟 2——建立大綱

抽出項目。一項一個事實。每個不確定用詞都要原樣抄下。

### 步驟 3——為每一項標出處

為每一項寫「對應原文」與「沒涵蓋」。再寫「這份大綱沒有收的部分」清單。

### 步驟 4——把大綱給使用者看

項目超過 5 個，或使用者要求時，就把大綱給使用者看。讓使用者刪除或修正項目。使用者否決的大綱，不要拿去做任何一階。

### 步驟 5——做出各階

使用者要哪幾階，就做哪幾階。照下面各階的規則做。

#### 第 1 階：受控文字

照 [ai-response-navigation](../../core/ai-response-navigation.md) 的 12.2 條：

- 一句一件事。英文約 15 到 25 個詞，中文約 25 到 40 個字。
- 一物一名。不要為了文采換名稱。
- 寫清楚誰做什麼。
- 一步一動作。流程寫成編號列表。
- 少用分號。
- 數字要帶單位。

每一行開頭保留項目編號，讀的人才找得到它在大綱裡的位置。

#### 第 2 階：Mermaid 圖

1. 步驟與因果用 `flowchart TD`。角色與交接用 `flowchart LR`。
2. 每個 `mechanism` 項目畫一個節點。用項目編號當節點編號。
3. 節點標籤取自項目文字。標籤裡要留下不確定用詞。
4. 不確定的項目畫成虛線節點或虛線邊（`-.->`）。
5. 不要畫沒有大綱編號的節點。
6. 在圖的下面，用文字列出你沒有畫的每一項，並各附一個理由。

```mermaid
flowchart TD
  O1["O1 訂單有時在付款步驟失敗"]
  O2["O2 可能：快取留著舊的價目表"]
  O1 -.-> O2
```

#### 第 3 階：單檔 HTML 解說頁

頁面必須是一個檔案。必須能離線開啟。不得從網路載入任何東西。

頁面**必須**符合：

- 所有 CSS 都放在一個 `<style>` 元素裡。
- 所有指令碼（若有）都放在一個內嵌的 `<script>` 元素裡。關掉指令碼，頁面仍要能用。
- `src`、`href`、`action`、`@import`、`url()` 裡不得有 `http://`、`https://` 或 `//` 開頭的網址。只允許頁內的 `#` 錨點連結。
- 不得有 `<link>` 元素。不得有網路字型、CDN 或外部圖片。
- 不得呼叫 `fetch`、`XMLHttpRequest`、`WebSocket` 或 `import()`。
- 不要載入 Mermaid 函式庫。把圖畫成內嵌 SVG，或畫成有樣式的清單。
- 原文中 HTML 會當成標記的字元，都要跳脫。

頁面依序包含：

1. 標題，加一句話說明原文是什麼。
2. 圖（若使用者要了第 2 階）。
3. 每個大綱項目一張卡片。卡片顯示編號、文字、有不確定語氣時的「尚未確認」標記、對應原文，以及沒涵蓋註記。
4. 「這份大綱沒有收的部分」清單。

最小骨架：

```html
<!doctype html>
<html lang="zh-Hant">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>解說頁：原文的簡短名稱</title>
<style>
  body { font: 16px/1.6 system-ui, sans-serif; max-width: 46rem; margin: 2rem auto; padding: 0 1rem; }
  .card { border: 1px solid #8884; border-radius: 8px; padding: .75rem 1rem; margin: .75rem 0; }
  .badge { background: #fd0; color: #000; border-radius: 4px; padding: 0 .4rem; font-size: .85em; }
</style>
</head>
<body>
<h1>解說頁</h1>
<p>一句話：原文是什麼。</p>
<section class="card" id="O2">
  <strong>O2</strong> 原因可能是快取留著舊的價目表。
  <span class="badge">尚未確認：可能</span>
  <p><em>對應原文：</em>第 1 段第 2 句</p>
  <p><em>沒涵蓋：</em>是哪一個快取。原文沒有說。</p>
</section>
</body>
</html>
```

### 步驟 6——交出之前先檢查

五項檢查都要跑。有一項沒過，就修好那一階，再跑一次。

1. **數量**：每一階的項目數，等於大綱的項目數，減去你列為「沒有畫」的項目。原文有 5 個步驟，每一階就是 5 個步驟。不是 4，也不是 6。
2. **沒有新項目**：每一階的每個項目都有大綱編號。找找看有沒有項目沒有編號。
3. **不確定語氣比對**：`hedge:` 不是 `none` 的每一項，每一階都要有同一個不確定用詞。比對的是該階與原文。任何語言都做得到。
4. **出處**：每一項都有指向某個位置的「對應原文」，也有「沒涵蓋」註記。
5. **離線**（只用於第 3 階）：在檔案裡搜尋 `http`、`//`、`<link`、`fetch(` 與 `XMLHttpRequest`。每一項搜尋，除了你從原文引用的文字，都必須是零命中。

### 步驟 7——回報

結尾放這張表。沒有這張表，不要交出任何一階。

| 項目 | 第 1 階 | 第 2 階 | 第 3 階 | 保留不確定語氣 | 對應原文 | 沒涵蓋 |
|------|---------|---------|---------|----------------|----------|--------|
| O1 | 有 | 有 | 有 | 不適用 | 第 1 段第 1 句 | 「有時」的頻率 |

有任何一項防護檢查沒過、又修不好，就說是哪一項、為什麼。不要回報成功。

## 什麼時候不要用

- 原文不到約 150 字。用 [ai-response-navigation](../../core/ai-response-navigation.md) 的 12.2 條改寫，並保留不確定語氣。不要做各階。
- 讀者是專家，需要密度高的原形。
- 任務是找出新的事實。本技能不做這件事。

## 衡量它有沒有幫助

本技能還沒有被證明有幫助。[eval-cases.md](eval-cases.md) 有 5 段原文，各附理解題與標準答案，並附一套跑法，會產出兩個數字：前後的答對率，以及防護違反次數。實跑需要模型呼叫，目前還沒做。實跑完成之前，不要宣稱本技能有效。

## 相關

- [ai-response-navigation](../../core/ai-response-navigation.md)：第 12 條，受控語言。12.1 條是防護 G2 的基礎。
- [documentation-guide](../documentation-guide/SKILL.md)：Mermaid 圖在專案文件中該放哪裡。
- [brainstorm-assistant](../brainstorm-assistant/SKILL.md)：相反方向，還沒有原文時用。

## 版本歷史

| 版本 | 日期 | 變更 |
|------|------|------|
| 1.0.0 | 2026-10-05 | 首次發佈。從同一份大綱做出三階。三條必須遵守的防護。評估案例。落實 dev-platform XSPEC-450 / DEC-125 D4。 |