---
name: cp-write
description: |
  要寫或改任何 CP（Critical Path）檔案之前必讀——動 system-dev/docs/3-specs/critical-paths/
  底下任何檔案、標記某關卡 ✅/◐/❌、或新增一條 CP 時自動載入。
  leo 2026-07-30：「上次已經跟你討論一次並且寫了正確範本，立刻全部忘光了」。
  三條鐵律：寫目的不寫功能／每步交出 deliverable／code 寫完沒部署不准標 ✅。
  另含 Logseq outliner 格式（給 leo 讀的 md 一律巢狀 bullet、禁表格平攤）。
---

# /cp-write — 寫或改一條 CP（Critical Path）

**要動 `system-dev/docs/3-specs/critical-paths/` 底下任何檔案之前，先跑這個。**

---

## 為什麼有這支 skill

leo 2026-07-30：「你去把寫 cp 的方法寫成 skill，**上次已經跟你討論一次並且寫了正確範本，立刻全部忘光了**。」

- **忘光的機制**（結構問題，不是記性問題）
  - 規範住在 `TEMPLATE-critical-path.md`（209 行）
  - CC 不會在動筆前主動讀 209 行文件 → 憑印象寫 → 寫成功能清單
  - 「該讀的文件存在」≠「會被讀到」
- **同一天內 leo 糾正四次**
  - 「不是有定義 CP 的寫法？outliner，步驟，有關任務」
  - 「你不要再去寫一個個功能，**要寫的是目的**，每次交出 deliverable」
  - 「上次說過，CP 有順序的跟無序的兩種」
  - 「CP 每個步驟要拉哪些任務，**不是自己編一堆新任務**…你去搜尋先前的你寫的範本」
- ⇒ 規範要在**動筆那一刻**被載入，不是躺在檔案裡等人想起來

---

## 六條鐵律

違反就是寫錯，不是風格問題。

### 1. 寫目的，不寫功能

> leo：「你不要再去寫一個個功能，要寫的是目的，達成那個目的，**每次交出 deliverable**，而不是交出一個程式碼打勾就完成了。」

- ❌ 錯：「`/cypher/search` 接 registry」
- ✅ 對：
  - **目的**：AI 拿到的答案必須是真的——假信號比沒答案更糟
  - **交付物**：查詢回應含 found/missing/unknown，found 附 input_schema
- **檢查法**：每步唸出來，聽起來像「我要改哪個檔案」→ 重寫成「達成什麼、交出什麼」

### 2. 從 tasks 池子撈任務，不在 CP 裡編新任務

> leo 2026-07-30：「**如果在這裡編任務，不就是廢掉了原本的 SDD，那到底要照 SDD 做事還是照 CP？**」

🔴 **2026-08-10 leo 定調：CP 只標編號，不重抄條目。原話——**

> 「CP 寫大計劃，加上描述，然後在 issues 寫明，**在 CP 標示 issue 編號**，
>   如果是在 issue 的內部 MD，一樣寫 `issue #2, task #?`，在 issue 從**標題層級**來找，
>   只要能 mapping 某 task。CP 一向就是寫計劃，把所需的 task 標示，**避免同一條目重抄一次**。」

> leo 2026-08-10（同日補充，這句是骨架）：
> 「**SDD 的 tasks 指向 issues，CP 的 tasks 指向 issues，永遠管理 issues。**」

- **三層，只有一層可寫**
  ```
  SDD tasks ──指向──┐
                    ├──▶  issue  ← 唯一管理處（勾選／s/* 狀態／執行細節／往返對話）
  CP  tasks ──指向──┘
  ```
  - **issue＝任務池子**（`issue-handle` 2026-08-09 定調）：任務本體、勾選、狀態都只住這裡
  - **SDD＝規格與設計**（為什麼要做、怎麼做）；它的 tasks 是**指向 issue 的清單**，不自己養 checkbox
  - **CP＝大計劃＋排序**（現在先做哪些）；寫目的與描述，任務只放**編號 pointer**＋`w=`
- **⇒ 兩邊都只是視角，動狀態一律回 issue。**
- 🔴 **CP 裡不准出現 `- [ ]` / `- [x]`**——checkbox 就是「在發號」，而 CP 不發號
  - 要知道做到哪 → 去看票。CP 只回答「這一步通不通」（三態）
  - **同一條目寫兩次 = 兩份真相 = 必然漂移**（2026-08-10 實錯：CP 四筆停在事發前的世界，
    issue 那邊才是對的；總管花一整輪在對帳）
- **定址：指到「一張票」，不指票裡的某一行**（D58，leo 2026-08-10）
  > leo：「**充分利用 gitea 的機制，不要硬做個不支援的機制，容易出錯。**」

  Gitea 原生就會把 issue 引用自動變成可點連結 ⇒ **CP 不必手貼網址、不必造錨點。**

  ```markdown
  - `w=9` Leo/arcrun-rag#52 — 重裝到已有資料的帳號，登入與資料庫一起壞
  ```

  - 🔴 **最好用的判準**：**需要指到票裡的某一行 ＝ 那張票該拆了。**
    這個限制反而**強迫出正確的顆粒度**
  - **票的刀口不是「大小」，是「狀態」**：問「它會不會需要跟隔壁那條不同的狀態？」
    會 → 獨立成執行票；不會 → 留在該票裡當 checkbox
  - **討論票 vs 執行票**：討論票是脈絡（不當工單追），執行票才是 CP 該指的東西
  - ⚠️ **已作廢：隱形錨點 `<a id="tNNN">`**（D53，同日上線同日推翻）——**不要撿回去**。
    它整段推理嚴謹，**但沒有先問「這個平台原生支援嗎」**。
    造任何機制前先問：「原生支援嗎？」「不支援是不是在說我方向錯了？」
- **自檢**：CP 上任何一行任務，拿它的編號去票裡找得到唯一一條嗎？
  - 找不到 → 你違規了。要嘛去票裡補，要嘛從 CP 刪掉
  - **絕不能留在 CP 裡當「CP 專屬任務」**
- **`w=` 的正確用法**（leo 原話）
  - 「從**很多任務**中找到跟現在目的**最近**的是誰，**把它排序到前面**」
  - 「**w 是標在 task 裡，這個任務原本在 SDD 的 tasks 中，跟現在的優先級有關，我把它拉出來到前面**」
  - ⇒ `w=` 的意思＝**這個 task 原本躺在 SDD 池子裡，因為跟當前目的相關，被拉到前面**
  - ⇒ 是池子任務**互相比較**後的排序，**不是對單一任務憑感覺打分**
  - ⇒ 同一步內的任務**依 `w=` 由高到低列**，高的先做
  - 🔴 **`w=` 只能標在任務表的任務上，不能標在步驟標題上**
    - leo 2026-07-30：「這個只是標題，不是從 SDD 拉出來的，**它的 w 是跟誰比是 9?**」
    - 【有序】卷的每步都是必經 ⇒ **不需要排序** ⇒ 標了就是假數字
    - 【無序】卷的並列項才需要 `w=`（那時它們互相比較，有意義）
  - 🔴 **`w=` 只排順序，不決定誰進 CP**——進 CP 的門檻是鐵律 5 的反事實測試（最小待辦）

> leo：「**tasks 是一個任務池子，CP 是編訂 sprint 的原則。**」

- **動筆前先做兩件事**
  - 看先前範本：`system-dev/docs/3-specs/autonomy-dispatch/sprint-2026-07a.md`
    （里程碑表 ＋ `P1>P2>P3` 任務板，做法一致，別重新發明）
  - 撈池子＝撈 issue（不是 grep `tasks.md` 的 checkbox，那份已經只是 pointer 了）：
    ```bash
    TOKEN=$(git remote get-url gitea | sed -E 's|.*//[^:]+:([^@]+)@.*|\1|')
    curl -s -H "Authorization: token $TOKEN" \
      "https://git.uncle6.me/api/v1/repos/Leo/<repo>/issues?state=open&labels=s/todo"
    ```
    - 🔴 **不帶 token 打私有 repo 回 `{"message":"not found"}`**，長得像「這裡沒東西」
      （2026-08-09 實錯：據此把 24 個 open issue 宣告成不存在）
- **怎麼列**：一律 outliner 清單（鐵律 6），**必要資訊是「編號 ＋ 一句話 ＋ w ＋ 執行者」**：
  ```markdown
  - `w=9` #2 task 3 — 讓 notify_leo 重新發得出訊息
  - `w=7` #2 task 7 — 👤 leo：拿你知道答案的東西查一次
  ```
  - 🔴 **沒有 checkbox**（鐵律 2，leo 08-10）——要看做到哪去點那張票
  - 🔴 **一句話是「指路」不是「複製」**：只寫到足以認出是哪一條，
    細節、實測輸出、踩到的坑**一律留在票上**
  - 🔴 **不用表格**（leo 07-31 拍板，見鐵律 6）——07-30 曾說「寫表格也可以」，已被此裁定取代
- **撈不到才是真缺口** → **去開票**（或在既有票裡加一條 task），然後 CP 標它的編號
  - 在**票**裡加，**不在 CP 裡加**
- **為什麼特別容易忘**：CP 看起來像 todo list，很自然就在裡面寫「我要做 A、B、C」
  - 那樣做 → 同一任務在票與 CP 各一份 → 必然漂移 → 兩邊都不可信
  - 2026-08-10 實錯：CP 四筆停在事發前的世界（已完成的還空著、已解除的還標危險），
    而票那邊是對的。總管花一整輪對帳，leo 當場問「**我到底要看什麼？**」

### 3. 每步有可執行的驗法

- 沒有驗法的步驟不算數——那是「宣告完成」的溫床
- 驗法要是**可執行的動作**（跑什麼指令、看什麼回應），不是「檢查是否完成」
- **考試三要素必須定義**（leo 2026-07-31：「誰主動、誰被動、正確答案是什麼，這些角色你沒有定義」）
  - **考生（主動）／受測物（被動）／正確答案**——三者寫在每步的「考試角色」行
  - **考不過＝迭代受測物**，不改題目、不怪考生
    - 受測物是環境（指引/引導）→ 考不過改環境（例：步驟 1「我給它一個環境它考不過，就是我的環境要迭代」）
    - 受測物是系統 → 回應不正確改系統（例：「haiku 給它一個需求回應不正確，就是系統要迭代」）
- **有前端的關，`HTTP 200` 不算驗過**
  - 要抓實際畫面內容：`curl <網址> | grep <該出現的字串>`

### 4. 用 PM 的態度定狀態：**deliver 才算通，不是我實測過就算**

> leo 2026-07-30：「最終不是要實測，**是要 deliver**，你在本地實測完沒推沒 deploy 也用不了，
> **最後要讓收的人可以實測**，你要抱着 **PM 的態度**，不是開發者的態度。」

- **判準只有一句**：**收的人現在能不能自己驗到？** 不能 → 沒通
  - 「收的人」＝leo／封測者／下一個 AI，看這條 CP 服務誰
- 三種狀態
  - `✅ 通` — **收的人已經驗到了**（貼他驗到的證據，不是我的）
  - `◐ 半通` — 我這端做完且驗過，但**還沒到收的人手上**；必須標明「卡在哪一段運送」
  - `❌ 斷` — 沒接上／沒發佈／沒人能用
- 🔴 **開發者態度 vs PM 態度**（開發者會說 → PM 要追問）
  - 「`tsc` 零錯誤、測試綠」→ 部署了嗎？
  - 「commit 了」→ push 了嗎？
  - 「push 了」→ 收的人拿得到嗎？（要不要重裝／解保險）
  - 「部署成功」→ 他點下去看到對的東西嗎？
- **運送鏈缺一段就不算通**：改完 → commit → push → 打包 → 部署 → **收的人重裝／重連** → 他驗到
  - 反覆的失敗模式：registry 機制完整但沒觸發／`acr search` 寫好沒發佈／
    ingest 通了沒人餵／daemon 修好但 leo 手上還是舊版
  - 每件都「做完了」，**收的人手上沒有**

### 5. 拉的是「最小待辦」（MVP），不是「相關任務清單」

> leo 2026-07-31：「CP 是要達成這個目標而**從池子裡拉出的最小待辦**，
> 如果不做這些也通過，就表示這些任務不屬於最小待辦。」
> 「最小待辦類似 **MVP** 概念——如果有 500 個任務，全部做完要很久，但現在要的是最小待辦。」

- **成員資格測試（反事實）**：拉任務進 CP 前問一句——
  「**不做這個，該步的驗法（考試）會不會掛？**」會掛才進。
  只是「跟目的相關」不夠：**相關 ≠ 必要**。
- **步驟驗法通過時，逐筆對帳還沒完成的**，三選一（leo 原話給的處置）：
  1. **評估出錯** → 檢討選任務的方法（寫進 mistakes.md）
  2. **移出 CP，以後完成**（票留著照常排，CP 刪掉那行 pointer）
  3. **已無需要** → 回票上結案
  - 🔴 非必要任務掛在 CP 上會**稀釋整個儀表板的訊號**——leo 看 CP 判「還差多遠」
- 🔴 **勾選一律回票上做，不在 CP**（鐵律 2，leo 08-10）
  - 舊版寫「做完就勾」（leo 08-01），指的是**別把做完的事留白**——那個意圖沒變，
    只是**勾的地方換了**：從 CP 換到票
  - CP 這一側對應的動作＝**該步的三態現況要更新**（✅／◐／❌），那才是 CP 的本職
- **要 leo 做的也是待辦**（leo：「如果有要我做什麼，這也是待辦，但**執行者是我**」）
  - 🔴 **它必須是一張撈得到的票，不能只住 CP**（leo 08-10：「執行到要我 input 時要標示 Stage，
    我去完成，**但 CP 的無法標示**」）
    - CP 是 markdown，**沒有 label 可掛 ⇒ leo 的看板撈不到 ⇒ 對他等於不存在**
    - ⇒ 人閘動作（arm／confirm／真機驗）一律**掛 `s/stage`**（規格見 `issue-handle`），
      CP 這邊只留一行 `👤 leo` 的 pointer
  - 標 `s/stage` **不等於交棒完成**——回覆裡要帶「打開什麼／該看到什麼／什麼算失敗」三件，
    且指令自己先打過（`issue-handle` 有全文）
  - 並同步 status「待 leo」清單＋每日催辦——不是只寫在對話裡
  - 🚚 「合主線／發版／部署／等 arm」＝**運送殘項**，另起一行標 🚚，不佔任務位
  - 🔴 **一筆待辦只准一個執行者**（leo 07-31：「這不是一個任務，是 2 個，
    兩個主詞不同怎麼寫在一起？」）——主詞不同就拆成多筆，各自標執行者；
    有先後依賴用「A 之後」寫在後筆開頭，不用「→」把兩人的事串成一筆
- **踩雷實例（2026-07-31 arcrun-usable 步驟 1）**：掛了 4 筆 `w=` 高的任務，
  一筆都沒做完、考試照樣 10/10 ＝全非最小待辦；而真擋 ✅ 的那筆
  （安裝器 seed skills）**反而不在清單上**。
  病根＝用「關鍵字相關度」順撈池子（語意相近的多半是同 SDD 的鄰居工單），
  但真最小待辦常在**別的環節**（交付鏈／安裝器／人閘）
  ⇒ **從驗法反推需要什麼，不從池子順撈相關的**。

### 6. 格式＝Logseq outliner，不用表格

> leo 2026-07-31：「我是個 Logseq 用戶……表格 + header 對閱讀不利，我看不出記錄彼此的層級，
> 全部平攤。**全部用 logseq outliner，可以用 outline + header，不要太花，保持乾淨簡潔。**」
> 「skill 寫明用 outliner，**不要一改版整個跑掉**。」

- **層級用巢狀 bullet 呈現**，不用表格——表格把層級平攤掉，Logseq 讀不出結構
- header 可以用，但只切大段（卷名／成功標準／六步／總驗收），不要每小節都開 header
- 不要太花：emoji／粗體節制，狀態記號（✅◐❌／👤）保留因為有功能
- 適用範圍：**CP、給 leo 讀的一切 md**（wiki、報告、交棒文件同此）
- 🔴 此條取代 07-30「寫表格也可以」——**改版時不准把格式改回表格**，本鐵律就是防跑掉的錨

---

## 執行流程

### 第一步 — 確認這是哪一條 CP

```bash
ls system-dev/docs/3-specs/critical-paths/
cat system-dev/docs/3-specs/critical-paths/README.md
```

- **新主題要另立一卷**，不塞進既有卷（leo：「你只有一個，這樣太大了」）
- **行數門檻**（07-30 實測後修正）
  - 目標 **100 行內**；**上限 200 行**（六步以上的卷，池子任務表格本身就佔百餘行）
  - 超過先問：**多出來的是「池子任務表格」還是「執行細節」？**
    - 池子任務表格 → **留著**，那是 CP 的核心（拉任務＋距離）
    - 執行細節／實測全文／糾正史 → 搬 `_evidence/`，CP 只留一行結論＋指針

### 第二步 — 判斷【有序】還是【無序】，標在標題上

- **【有序】** — 前步不通，後步沒意義
  - 寫法：步驟 1→N 鏈狀；斷點按順序列、標「前置」
  - 例：安裝→萃取→查詢→MCP／AI 想到→查詢→替換→執行
- **【無序】** — 並列能力，各自算分
  - 寫法：每項獨立標 `w=`／狀態；**不寫「前置」**
  - 例：「知識可收集、可查、可追」＝三種能力並列
- **判斷法**：把第 2 步拿掉，第 3 步還有意義嗎？
  - 沒意義 → 有序
  - 還有意義 → 無序
- **可混合**：有序主鏈 ＋ 無序支線（支線另開一段標【無序】，別硬塞進鏈裡）

### 第三步 — 每步寫四件事

```markdown
### 步驟 N｜<一句話目的>　`w=9`　◐ 半通

**目的**：<達成什麼。沒參與的人也看得懂>
**交付物**：<交出什麼可驗的東西。不是「改好某個檔案」>
**驗法**：<可執行的動作。有前端要抓畫面內容>
**現況**：<實測到什麼。附證據>

**最小待辦**（鐵律 5：過反事實測試才進；要 leo 做的標 👤 leo）
- [ ] <任務——出處 SDD>
- [ ] 👤 leo：<人閘動作>

**移回 SDD 池**（曾拉進來但驗證非必要的，留一行去向）
```

### 第四步 — 斷點與「不在 CP 上」

- 🔴 斷點段（outliner，一行一斷點）：`- 步 N <斷點>——前置：<步>；<為什麼卡>`
- ⚪ 不在 CP 上：`- <項目>（<為什麼不阻斷>）`
  - **一定要寫**——不寫下來就會反覆被它吸走注意力

### 第五步 — 進度數字

- 卷尾一行：`**進度：N 完成／M 進行中／K 未做（共 T）**`
- 有機械驗收（如 `verify.sh`）→ **以它為準**，並註明「此清單是人看的」

---

## 收工檢查

逐條自問，答不出來就是沒寫完。

1. 每步都是「目的＋交付物」，不是「改哪個檔案」？
2. 子項是**從池子撈的**（有「出處」欄）？撈不到的標了 `➕ 待加 <SDD>`？
3. 動筆前**看過先前範本**（`autonomy-dispatch/sprint-2026-07a.md`）？
4. 標了【有序】／【無序】？
5. 每步驗法**可執行**？有前端的抓了畫面內容？
6. **有 `✅` 的，是「收的人驗到」的證據，不是我自己測過？**
   - 運送鏈走完了嗎：改完 → commit → push → 打包 → 部署 → **收的人重裝** → 他驗到
   - 缺任一段 → 最多 `◐`，且要標「卡在哪一段」
7. 寫了「不在 CP 上」？
8. 這一卷在 200 行內？超過的部分是「池子任務表格」（可留）還是「執行細節」（要搬）？
9. **CP 檔真的改了**？（leo 07-26：「我看 CP 也沒用，因為你執行時沒去更新」）
10. **每筆任務都過了反事實測試**（不做它驗法會掛）？要 leo 做的標了 👤 並進催辦？
    驗法通過的步驟，空 checkbox 對帳完了（檢討／移回池子／標完成或刪）？
11. **全卷 Logseq outliner、零表格**（鐵律 6）？層級縮排看得出來？沒有太花？

---

## 相關

- 完整規範（含踩雷案例）：`system-dev/docs/3-specs/TEMPLATE-critical-path.md`
- 分卷規則：`system-dev/docs/3-specs/critical-paths/README.md`
- 先前範本（拉任務＋標距離）：`system-dev/docs/3-specs/autonomy-dispatch/sprint-2026-07a.md`
- 執行細節該放哪：`system-dev/docs/3-specs/critical-paths/_evidence/`