ISEP/commands/cp-write.md

name, description

name	description
cp-write	要寫或改任何 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 不必手貼網址、不必造錨點。

  - `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 了）：

    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 ＋ 執行者」：

  - `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

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 步還有意義嗎？
  • 沒意義 → 有序
  • 還有意義 → 無序
• 可混合：有序主鏈 ＋ 無序支線（支線另開一段標【無序】，別硬塞進鏈裡）

第三步 — 每步寫四件事

### 步驟 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/