docs: idd-plan ↔ idd-diagnose 的關係與順序未寫清楚 — 使用者與其 AI 都推論出「跳過 diagnose 直接 plan」

[kiki830621]

Problem

使用者文件沒有寫清楚 idd-plan 與 idd-diagnose 的關係與先後順序。結果是：使用者問了三次仍不確定，使用者的 AI 自行推斷出「不用 diagnose，直接用 plan」（與設計相反），而 maintainer 在同一段對話裡給出了兩種互斥的說法。

Original text（Telegram 私訊，2026-07-08 15:00–15:25。對話對象為 IDD 早期使用者，以 K 代稱 — 見文末 Privacy note）：

15:00 K：issue>plan>deep research>verify>report>close
15:00 K：過程中>comment
15:00 K：那如果我想研究問題，這樣可以嗎
15:01 Che：issue後面我通常會先 /diagonose
15:01 Che：diagonose之後你要補deepresearch都可以
15:01 K：那不用plan嗎
15:02 Che：diagnose 會判斷需不需要plan
15:03 K：好的
15:06 K：他之前說deep research就好，然後AI現在就跟我說不用diagnose, 直接用plan
15:08 Che：看起來是我說明沒寫完整
15:08 Che：你照著她做我想應該也是可以
15:08 Che：plan可以取代diagonoe
15:25 K：像我剛剛提出的問題老師覺得有哪些需要開issue嗎
15:25 Che：就是要寫清楚plan, diagonose的關係，要讓使用者清楚知道順序 之類的

（同一使用者在 07-05 另有 report(收斂) 的功能詢問，經確認是 AI 幻想出來的 skill 名稱 — 見文末 sibling 說明，同屬「說明不完整 → AI 自行補完」這個 class。）

Type

docs

Expected

使用者只讀 plugins/issue-driven-dev/README.md 就能回答三個問題：

1. idd-plan 在 pipeline 的哪個位置？
2. 誰決定要不要跑 idd-plan — 使用者自己選，還是 idd-diagnose 判定？
3. 可不可以跳過 idd-diagnose 直接叫 /idd-plan？代價是什麼？

Actual

三個問題目前都答不出來：

位置	現況	問題
README.md:52 canonical pipeline 圖	idd-issue → idd-diagnose → idd-implement → idd-verify → idd-close（5 格編號 ①–⑤）	完全沒有 idd-plan。使用者看圖不會知道它存在於流程何處
README.md:60 skill 表格	「Plan tier approval gate ... sits between Simple direct-implement and Spectra spec-contract path」	用的是內部 routing tier 語彙。「sits between Simple and Spectra」回答的是「複雜度光譜上的位置」，不是使用者問的「執行順序上的位置」
references/usecase-routing.md:49（row 9）	idd-diagnose` 判 Plan → `idd-plan` → `idd-implement	✅ 這是正確答案，但埋在 reference 文件第 49 行，README 沒有從 pipeline 圖指過來
references/usecase-routing.md:15 決策樹	「看 Implementation Plan 給人 approve（Plan tier） → idd-plan」	⚠️ 這行單獨讀反而支持錯誤解讀：「我想要 plan → 叫 idd-plan」。沒說 diagnose 必須先跑
全 plugin 文件	grep 取代 diagnose / skip diagnose / 跳過 diagnose → 0 命中	「plan 能不能取代 diagnose」這個問題在文件裡根本沒被回答過。所以 15:08 的口頭答覆「plan可以取代diagonoe」既無文件依據，也與 row 9 的設計矛盾

三個獨立的失敗證據：

1. 使用者連問兩次（15:01「那不用plan嗎」、15:06 重提）
2. 使用者的 AI 給出與設計相反的建議：「不用 diagnose, 直接用 plan」。這不是 AI 亂講 — 在現有文件下，idd-plan 看起來就是一個和 diagnose 平行的 stage
3. maintainer 自己給出互斥的兩種說法：15:02「diagnose 會判斷需不需要plan」（diagnose 是上游 router，tier 是它的輸出）vs 15:08「plan可以取代diagonoe」（peer，可互換）。這兩句不可能同時為真

Impact

• idd-diagnose 是 IDD 的 router（Layer 1 disqualifier → Layer V vagueness → Layer 2 Spectra → complexity hard gate → Layer P）。跳過 diagnose 直接 plan，等於繞過整個 routing 機制：Layer V 的模糊度把關、#129 的 complexity hard gate、meeting-type 分流全部不會執行
• 新使用者的第一手心智模型會定型在錯的形狀上，之後很難改
• MANIFESTO 的核心主張是「Every issue is diagnosed before implementation — no guessing」（README.md:13）。文件容許使用者推論出「可以跳過 diagnose」，直接侵蝕這條主張

Suggested scope（供 diagnose 參考，非定案）

1. README pipeline 圖旁補一行標示 Plan/Spectra 是 diagnose 的輸出 tier，不是平行 stage
2. skill 表格 idd-plan 那列改用使用者語彙（誰觸發、何時觸發），不用 tier 光譜語彙
3. 明文回答「能否跳過 diagnose 直接 plan」— 不論答案是可以或不可以，寫下來 + 寫代價
4. usecase-routing.md:15 決策樹那行補上 diagnose 前置條件，避免單獨被讀成 entry point

補充：實作層其實已有明確答案（建立本 issue 後查證）

plugins/issue-driven-dev/skills/idd-plan/SKILL.md Step 1 的 diagnosis lookup table（第 62 行）已經明文規定：

Complexity	行為
Plan	✅ 預期 — 繼續
Simple	⚠️ 詢問 user
Spectra（含 alias SDD-warranted）	⛔ 提示改走 /spectra-discuss
(missing)	⛔ 提示「找不到 diagnosis，先跑 /idd-diagnose #NNN」並 abort

也就是說 shipped 實作的答案是明確的：/idd-plan 無法取代 /idd-diagnose — 沒有 ## Diagnosis comment 時它會 hard abort，連跑都跑不起來。同一份 SKILL.md 第 17 行也寫「由 idd-diagnose Step 3.5 的 Complexity verdict 決定」，Simple / Plan / Spectra 三個 tier 是 diagnose 的輸出。

這把本 issue 的性質從「需要做決定」改成「答案已經存在，但只存在於 skill 內部，沒有進到任何使用者面向的文件」，而且產生兩個更尖的問題：

1. maintainer 的口頭答覆與 shipped 行為矛盾 — 2026-07-08 15:08「plan可以取代diagonoe」與 SKILL.md:62 的 hard abort 直接衝突。需確認是口誤，還是實作應該放寬
2. 使用者的 AI 給的建議會在 runtime 直接失敗 — 「不用 diagnose, 直接用 plan」照做會撞 abort。使用者原本會得到一個看不懂的錯誤，而不是一個能理解的說明

修正後的 Expected 因此收斂為：把 SKILL.md:62 已經編碼的規則搬到使用者讀得到的地方（README pipeline 圖 + skill 表格），並確認口頭答覆與實作何者為準。不需要重新設計任何機制。

Clarity Surface(idd-clarify run 2026-07-26T00:00:00Z)

Type	Source	Suggested canonical	Status
ambiguity	「那不用plan嗎」/「plan可以取代diagonoe」	來源的「plan」有兩個所指：(a) /idd-plan skill；(b) idd-diagnose Step 3.5 輸出的 Plan complexity verdict / tier。「plan 能否取代 diagnose」的答案依所指而異 —— (a) 不能（SKILL.md:62 hard abort）；(b) 問題不成立（tier 是 diagnose 的產物，無法取代產生它的東西）。文件修正時兩個意思必須用不同詞面	resolved @ 2026-07-25T16:08:23Z (reason: 兩個所指已在 body 補充段釐清，並升格為修正需求：文件須用不同詞面區分 /idd-plan(skill) 與 Plan(tier))
missing-context	「你照著她做我想應該也是可以」/「plan可以取代diagonoe」	maintainer 的 live 答覆與 shipped 實作（skills/idd-plan/SKILL.md:62）衝突。待 maintainer 裁決：是實作該放寬（允許無 diagnosis 直接 plan），還是口頭答覆為口誤（文件照實作寫）。此為 diagnose 前必要輸入	resolved @ 2026-07-25T16:08:23Z (reason: maintainer 2026-07-26 授權裁決，採實作為準 — SKILL.md:62 hard abort 是規則，07-08 口頭答覆為口誤；修正範圍純文件+生成器，零 gate 邏輯改動)
terminology	「diagonose」/「deepresearch」/「皆在diagonose上」/「家入research」	來源為即時通訊輸入，含 typo：diagonose→diagnose、皆在→接在、家入→加入。逐字原文依 IC_R007 保留不改，本列僅供 downstream 讀者對照	dismissed @ 2026-07-25T16:08:23Z (reason: 來源 typo 依 IC_R007 刻意逐字保留，僅供 downstream 對照，無行動項)

Linked-Context Siblings Filed

本 issue 來源（單一 Telegram 對話串，2026-07-04 至 2026-07-13）掃出 5 個 sibling concern。Filed 3、surfaced-but-not-filed 2：

#	Concern	處置
1	idd-plan ↔ idd-diagnose 關係與順序未寫清楚	本 issue（maintainer 2026-07-08 15:25 明確指定要開）
2	Claude Deep Research 未整合進 IDD、無 documented 接法	filed → #277
3	issue 已 closed 但事情還要做，缺 reopen / resume-implement 路徑	filed → #278
4	AI 幻想出不存在的 IDD skill（使用者 2026-07-05 問「report(收斂) > 你有寫這個功能嗎」，經 maintainer 確認為 AI 幻覺）	不另開 — 與本 issue 同一 root cause（使用者文件不完整 → AI 自行補完），已作為佐證寫入本 issue Problem 段。若日後出現形狀不同的第二個幻覺案例再獨立 file
5	「AI 有能省力就省力的傾向」（使用者 2026-07-13 觀察）	不 file — IC_R011 category (a) unactionable。maintainer 當下回覆「要看是哪一個模型 不然這樣會有困難」，即缺 model / repro 資訊時無法轉成可行動 issue。本 repo 已有 .claude/rules/attribute-assessment.md 的 Lazy Developer adversary lens 涵蓋同一 class。取得具體 repro（哪個 skill、哪個 gate 被跳過、哪個 model）後再 file

（/idd-issue Step 4.6 clarity surface + Step 4.7 IC_R011 light-touch sister sweep）

Privacy note

原始來源為第三方 Telegram 私訊。逐字內容原樣保留（IC_R007），但對話對象的真名以 K 代稱 — 本 repo 為 public，第三方真名不必要地進入公開 issue 不符 privacy-scrubbing 紀律。若 maintainer 認為應具名，可自行 edit 補回。

---

Current Status

Phase: planning
Last updated: 2026-07-26 by idd-plan

Key Decisions

• Phase 1 已實作並開 draft PR fix(skills): name the diagnosis precondition in idd-plan's description (#276) #279；本 issue 不因該 PR 結案（Phase 2 尚未開工）
• 實測 17 個 skill：不符 house pattern 的是 5 個不是 1 個，5 個併入 Phase 1 同修（[enhancement] Plan tier triggering criteria 太寬鬆 — 大範圍改動應 MUST-trigger Plan #129 契約 / feature: /idd-all chain-solve mode — 自動接續解 spawned issues + 單 review PR #44 教訓）
• A4 assertion 用明列 allowlist 而非機械推導 —— 推導式會誤傷 idd-close 的 meeting fallback 字串
• 新 description 附「改跑 /idd-diagnose #N」的補救指示而非純警告，避免反向嚇阻 AI 永不選 idd-plan
• drift-guard 自述只驗「有沒有」不驗「寫得好不好」，品質仍留給 review 人判斷（同 docs-catalog-sync 立場）
• Root cause 定位於 skills/idd-plan/SKILL.md frontmatter description 未載明 diagnosis 前置 —— 該處是 AI 選 skill 時唯一可見的表面，且 idd-plan 是唯一同缺 Use when: 與 防止的失敗: 的 lifecycle skill
• 採「以實作為準」：保留 SKILL.md:62 的 hard abort，不放寬讓 plan 獨立跑（maintainer 2026-07-26 授權裁決）
• wiki 流程圖頁由 docs/workflows.md 自動生成，不手寫、不建雙 source of truth（maintainer 2026-07-26 選定）
• Complexity = Plan（Layer P：generator 解析契約 decision-heavy／檔案順序依賴／跨 repo 寫入 wiki 屬 irreversible side effect）
• 交付分兩階段：Phase 1（description + drift-guard，可獨立出貨）／Phase 2（generator + wiki + README 指路）

Scope Changes

• Phase 1 實際觸及 8 檔（5 個 SKILL.md + 新 drift-guard suite + README + CHANGELOG），超出 diagnosis 預估的 1 檔
• 由原本的「補文件說明順序」擴大為三軸：機器面向 description 修正 + 人面向自動生成流程圖 + drift-guard 結構性防再犯
• drift-guard assertion 涵蓋範圍由「lifecycle skill」擴大為「所有 IDD skill」（sister sweep 發現 idd-clarify 同屬 house-pattern 缺漏，併入 Phase 1，不另開 issue）

Blocking

• (none) —— Phase 1 待 maintainer review draft PR fix(skills): name the diagnosis precondition in idd-plan's description (#276) #279；Phase 2 未開工，不阻塞 Phase 1

Commits

• 1e46698 fix(skills): name the diagnosis precondition in idd-plan's description

[kiki830621]

🎯 Decision

Original (2026-07-26，maintainer 於本 issue 建立過程中補充)：
「就是我覺得path應該要做好，然後做成一個流程圖放在wiki，不然我也會搞不清楚」

決定

本 issue 的交付形狀定為：把 path 定案 → 畫成流程圖 → 放進 GitHub wiki，而不是只在 README 補幾行文字說明。同時，受眾從「新使用者」擴大到包含 maintainer 自己（「不然我也會搞不清楚」）—— 這不是 onboarding 文件，是日常參照用的導航圖。

Rationale

這條決定改變了 scope 的形狀，理由有三層。

第一，受眾改變了 artifact 的形狀。 原本 issue 的 framing 是「新使用者看不懂順序」，若如此，README 補一段文字就夠。但 maintainer 明說自己也會搞不清楚 —— 一個每天在用的人都需要查的東西，就不能是散在 README 段落裡的敘述，必須是可以一眼掃完的圖。文字說明服務「讀一次建立心智模型」；流程圖服務「反覆查詢」。兩者不能互相取代。

第二，「path 應該要做好」的前置工作其實已經大致完成，缺的是 surface 與 render。 查證現況：

項目	現況
Path catalog	✅ 已存在 —— docs/workflows.md，565 行，7 大類（A 單 issue lifecycle / B convenience orchestrator / C batch / D multi-finding dispatch / E verify-only / F resume / G ancillary），共 31 條具名 path（P-atomic / P-plan-gated / P-spectra-discuss-first / P-cluster-pr / P-chain-from-root …），且已含 § Path × Skill Matrix、§ Path Selection Decision Tree、§ Anti-patterns
README 指路	❌ 完全沒有 —— README.md 對 docs/workflows.md 的唯一提及埋在 CHANGELOG 表格的 v2.56.0–v2.71.0 那格 cell 裡。使用者不可能找到
流程圖	❌ 全 repo 0 個 mermaid 圖表（grep -rln mermaid 無命中）。Decision Tree 目前是純文字階層
Wiki	✅ 已啟用且活躍 —— Home.md / _Sidebar.md / Changelog.md + 8 篇 dated session log（20260711 ~ 20260719）。但沒有任何 path / workflow 頁，_Sidebar.md 目前只有 Changelog 一個區塊

所以工作不是「重新推導 path」，而是 (a) 把已有的 31 條 path render 成圖、(b) 放進 wiki 並在 _Sidebar.md 開一個新區塊、(c) 從 README 指過去。這比原本預期的小很多，但價值集中。

第三，這條決定與本 issue 原本的核心矛盾直接相關。 本 issue body 的補充段已查證：skills/idd-plan/SKILL.md:62 規定 missing diagnosis → hard abort，即 /idd-plan 無法取代 /idd-diagnose；而 docs/workflows.md 的 P-plan-gated path 也是同一個順序。換句話說，正確答案在 path catalog 裡已經寫對了，錯的是它沒被畫出來也沒被指路，所以 maintainer 在即時對話中憑記憶回答時說成了「plan可以取代diagonoe」。這正是「連我也會搞不清楚」的具體證據 —— 流程圖要解的就是這個。

為何選 wiki 而非 README。 兩者不互斥，但分工明確：README 是 plugin 的 entry point，適合放「一張最小主幹圖 + 一行連結」；wiki 適合放完整的 31-path 航線圖（會很大、會頻繁更新、不該每次改都動 plugin 版本）。maintainer 指定 wiki，符合這個分工。排除的選項：把大圖直接塞進 README —— 會讓 README 變得難讀，且 path catalog 每次增修都要 bump plugin 版本，維護成本不對稱。

對 Expected 的修正

原 Expected 的三個問題仍然要被回答，但交付物改為：

1. wiki 新頁（暫名 Workflow-Paths）：mermaid 流程圖呈現 idd-issue → idd-diagnose →（Simple / Plan / Spectra / meeting 四出口）→ …→ idd-close 主幹，並標明 idd-plan 是 diagnose 的輸出分支而非平行 stage
2. _Sidebar.md 新增區塊指向該頁
3. README pipeline 圖旁一行連結指向 wiki 頁
4. docs/workflows.md ↔ wiki 的同步紀律：兩者關係要寫清楚（誰是 source of truth、如何避免漂移）—— 這點需在 diagnose 階段決定，否則會產生第二份會腐爛的平行文件

Related

本 comment 為 #276 的 scope 修正。sibling：#277（Deep Research 整合形狀）、#278（reopen / resume-implement 路徑）—— 兩者的結論若成立，也應反映在同一張流程圖上。

[kiki830621]

Diagnosis

Type

docs

Root Cause / Analysis

原始 issue 把問題框成「使用者文件沒寫清楚順序」。診斷過程中 maintainer 補了一句關鍵修正：

「但我覺得他得問題就是她覺得自己可以plan就好」

這句話把根因往下推了一層，而且是對的。真正的失效不是「人讀不懂」，是「AI 在選 skill 的當下，讀到的 metadata 讓它合理地推論出 plan 就夠了」。查證如下。

三個表面，只有一個是 AI 選 skill 時讀得到的

表面	內容是否正確	AI 何時讀到
docs/workflows.md § P-plan-gated（第 49–58 行）	✅ 完全正確 —— chain 寫 idd-issue → idd-diagnose → idd-plan → idd-implement → …，Assumptions 明寫「diagnose 後 verdict = Plan」	❌ 人工文件，AI 不會主動載入；README 也沒指過來
skills/idd-plan/SKILL.md Step 1 lookup table（第 62 行）	✅ 完全正確 —— _(missing)_ diagnosis → ⛔「找不到 diagnosis，先跑 /idd-diagnose #NNN」並 abort	❌ 只有在 AI 已經決定要跑 /idd-plan 之後才載入。決策已經做完了，這道閘只是事後攔截
skills/idd-plan/SKILL.md frontmatter description	❌ 這裡是空的	✅ 這是 AI 選 skill 時唯一讀得到的東西

根因：idd-plan 的 description 是唯一一個沒說前置條件的

idd-plan 的 description 全文：

「Plan-mode 實作。在 idd-implement 的 TDD loop 之前，先用 Claude Plan Mode 把 Implementation Plan 呈現給使用者審查、approve 後才動手。介於 Simple（直接 implement）和 Spectra（完整 spec/proposal/tasks artifacts）之間的中間層。」

零次提及 diagnosis。 而且它把自己定位成相對於 idd-implement 的位置（「在 idd-implement 的 TDD loop 之前」），不是相對於 idd-diagnose。一個只讀得到這段的 AI，會得到「plan 是進 implement 前的一個自足入口」這個印象 —— 它的推論在它可見的資訊上是正確的。

對照姊妹 skill idd-implement 的 description：

「按照 diagnosis 的策略實作，嚴格控制 scope。… Use when: diagnosis 確認後、開始寫 code 時。防止的失敗：scope creep …」

同樣是 post-diagnose 的 skill，idd-implement 明寫前置，idd-plan 沒有。

Sibling audit：這是單點異常，不是全域風格差異

掃過全部 6 個 lifecycle skill 的 frontmatter description：

Skill	Use when:	防止的失敗:	提及 diagnosis 前置
idd-issue	✓	✓	✗（不需要，它是入口）
idd-diagnose	✓	✓	✓
idd-plan	✗	✗	✗ ← 唯一全空
idd-implement	✓	✓	✓
idd-verify	✓	✓	✗（不需要，前置是 implement）
idd-close	✓	✓	✗（不需要，前置是 verify）

idd-plan 是唯一同時缺 Use when: 與 防止的失敗: 的 —— 其他五個都遵守這個 house pattern。這不是有意的設計選擇，是 v2.36.0 新增 idd-plan 時漏掉了既有慣例。

為什麼「AI 傾向省力」讓這個漏洞必然被踩到

使用者 2026-07-13 的觀察（「ai是不是有一個傾向啊 就是能省力就省力」）在這裡是機制而非旁支：description 沒有硬性訊號時，一個在多個候選 skill 之間選擇的 AI 會偏好步數少的路徑。plan 讀起來像是 diagnose 的超集（「計畫」聽起來包含「分析」），所以省一步的推論既省力又看似合理。description 的沉默 + AI 的省力偏誤 = 必然的錯誤路由，不是偶發。

這也解釋了為什麼 maintainer 自己 2026-07-08 15:08 會脫口說出「plan可以取代diagonoe」—— 憑記憶回答時，腦中浮現的也是 skill 名稱的字面語感，而不是那張埋在 docs/workflows.md 第 49 行的 chain。

Impact

影響的檔案

檔案	影響
plugins/issue-driven-dev/skills/idd-plan/SKILL.md（frontmatter）	根因所在。3 行內可修
plugins/issue-driven-dev/README.md（:52 pipeline 圖 + :60 skill 表格）	人面向的第二現場
docs/workflows.md	內容正確但無入口；若採自動生成，需確保結構可機械解析
wiki Workflow-Paths + _Sidebar.md	新增（生成產物）
新增 generator script	由 catalog 產 mermaid 並推 wiki
drift-guard 測試	新增 assertion 防同類再犯

影響的使用者流程

• 任何透過 AI 選 skill 的使用者（= 絕大多數）都可能被路由到 /idd-plan 而跳過 diagnose，撞上 abort。使用者體驗是「照 AI 說的做卻壞掉」
• 撞 abort 是好的失敗（fail-fast，訊息也指名了修法），所以沒有靜默損害；成本是使用者的困惑與往返
• maintainer 自己憑記憶回答時也會答錯 —— 影響外溢到對外教學

Strategy

分兩階段。Phase 1 修根因，小而急；Phase 2 是 maintainer 指定的導航建設。

Phase 1 — 機器面向（根因，可獨立出貨）

• 改 skills/idd-plan/SKILL.md frontmatter description，補齊 house pattern：明寫 Use when: diagnosis 確認且 Complexity 判為 Plan 之後 + 防止的失敗: 跳過 diagnose 直接 plan（tier 是 diagnose 的輸出，無 diagnosis 會 hard abort）
• 同步 .claude-plugin/plugin.json 內對應描述（若有）
• 結構性防再犯：新增 drift-guard assertion —— 每個 lifecycle skill 的 frontmatter description 必須含 Use when: 與 防止的失敗:；post-diagnose 的 skill（idd-plan / idd-implement）另須提及 diagnosis 前置。把 house pattern 從口頭慣例升格為測試

Phase 2 — 人面向導航（maintainer 指定：自動生成）

• 決定 generator 的解析契約：docs/workflows.md 的 #### P-<name> — <title> + 其下 fenced chain block 為機械解析錨點；必要時先正規化既有 31 條 path 的格式
• 寫 generator：由 catalog 產出 mermaid → 輸出 wiki Workflow-Paths.md（頁首標注「本頁自動生成，勿手改；來源 docs/workflows.md」）
• 決定推送機制（CI on push to main / make wiki 本地 target / 手動跑）—— 見 Risks 的 wiki 覆寫風險
• 更新 wiki _Sidebar.md 新增區塊
• README.md pipeline 圖旁加一行連結指向 wiki 頁，並標明 idd-plan 是 diagnose 的輸出分支而非平行 stage
• README.md:60 skill 表格 idd-plan 那列改用使用者語彙（誰觸發、何時觸發），不用 tier 光譜語彙

已裁決、不做的事

• 不放寬 idd-plan 的 hard abort（2026-07-26 maintainer 授權裁決，採實作為準）。理由：tier 是 diagnose 的輸出，無 diagnosis 就無 tier，放寬等於讓 AI 自己猜 tier —— 正是 README:13「no guessing」要擋的；且 idd-all / idd-all-chain 以 grep ^## Diagnosis 判 phase，允許 planning 而無 diagnosed 會在 phase 狀態機挖洞
• 不修改 07-08 對話的逐字原文（IC_R007）

Conflict Class

A_parallel_safe

Phase 1 只碰 skills/idd-plan/SKILL.md 與新增測試；Phase 2 碰 README / docs / 新 script / wiki（獨立 git repo）。無共享 mutable 資源、無單寫者資源、無共享 submodule。唯一例外需注意：wiki 是獨立 remote，若未來有其他 job 同時推 wiki 會競寫 —— 但目前僅此 issue 觸及，故仍判 A。

Complexity

Plan

觸發的 Layer P 信號（Layer 1 未命中之判定理由見下）：

• Decision-heavy with 2+ valid approaches —— generator 的解析契約（依賴既有 markdown 結構 vs 在 catalog 加機器可讀標記 vs 抽出獨立資料檔）、推送時機（CI vs make target vs 手動）、31 條 path 如何在一張圖內保持可讀（單張大圖 vs 分類分圖）三處都有多個合理解且會影響 code shape
• 2+ 檔案有順序依賴 —— generator 必須先定出 wiki 頁名與錨點，_Sidebar.md 與 README 連結才能寫；catalog 格式正規化必須先於 parser 定案
• 觸及 risk-sensitive 邊界（irreversible side effects） —— generator 會寫入 另一個 git repo（*.wiki.git）。覆寫邏輯有 bug 會清掉 wiki 現有 11 個頁面（含 8 篇 session log 與 Changelog.md），且 wiki 的誤刪回復比 code repo 麻煩

為何 Layer 1 未命中（此判定可爭議，明列理由供覆核）：Layer 1 的 narrative disqualifier 針對的是 fluid prose（摘要改寫、wording polish、translation）。本 issue 在 maintainer 選定「自動生成」之後，主要 deliverable 已包含一支具解析邏輯的 script 與跨 repo 寫入，不屬 fluid prose 類。若當初採「純手寫 wiki 頁」，Layer 1 會命中而判 Simple —— 是 maintainer 的 SoT 選擇把它推進 Plan tier。

硬閘（#129）：Hard-gate: not triggered — 預估觸及 idd-plan/SKILL.md、README.md、docs/workflows.md、新 generator script、wiki 2 檔，檔數雖近門檻但其中 wiki 兩檔為生成產物、且無被 ≥2 檔引用的 shared abstraction 被改動

Layer 2（Spectra）未滿足：generator 是 repo 內部維護 script，不對 future callers 暴露 published API / protocol / skill / tool surface。docs/workflows.md 被機械解析確實形成一層格式契約，但消費者僅此單一內部 generator，非 external caller，故不升 Spectra。

→ 建議 pre-implementation staging: superpowers:brainstorming（Phase 2 的三個 decision point 值得先對齊方向再進 plan）

Risks

風險	說明	緩解
generator 覆寫 wiki	wiki 現有 11 頁（Home / _Sidebar / Changelog + 8 篇 dated session log）。全量覆寫式推送會清掉它們	generator 只得寫入自己那一頁 + 以 append/replace-block 方式改 _Sidebar.md；推送前 dry-run diff；先在 fork 或 branch 驗證
生成物與 catalog 漂移的反轉	自動生成杜絕人工漂移，但若 generator 壞掉沒人發現，wiki 會停在舊版且看起來仍「權威」	生成頁標注來源 commit SHA + 生成時間；CI 失敗要可見
catalog 格式正規化的連帶風險	為了可解析而改動 docs/workflows.md 既有 31 條 path 的結構，可能破壞現有引用（idd-all-chain Phase 0.4.5 的 anti-pattern A3 cite 等）	正規化前先 grep 全 repo 對 docs/workflows.md 的引用；優先採「不動既有結構、只依賴現有 heading pattern」的解析法
Phase 1 被 Phase 2 拖住	根因修正只要 3 行，但若綁在同一個 PR 等 generator 做完，實際的錯誤路由會持續發生	Phase 1 獨立出貨（見 Strategy）；本 issue 允許分兩個 PR
description 改動的 side effect	frontmatter description 是 skill 選擇的輸入，改動會影響所有 AI 的路由行為	這正是目的；但需確認新措辭不會反向讓 AI 過度避開 idd-plan

Residue

原 issue 的意圖裡有一部分無法 operationalize：maintainer 說「不然我也會搞不清楚」—— 這句的完整訴求是「讓我自己憑記憶回答學生時也不會答錯」。流程圖能降低查詢成本，但無法保證 maintainer 在即時對話中會去查。2026-07-08 那次答錯的當下，docs/workflows.md 第 49 行其實已經寫對了，錯誤仍然發生 —— 因為即時對話的瓶頸是「不知道自己記錯了、所以不會去查」，不是「查不到」。本 issue 交付的 artifact 只能改善後者。前者屬於個人工作習慣層面，不接進 function/argument，明確標記不靜默丟棄。

來源完整性缺口（誠實揭露）

本 issue 的來源逐字稿含 5 個 圖片 placeholder（11:15 / 11:23 / 07-08 14:58 / 07-08 15:01（Che 傳，正在解釋 diagnose 判定 Plan） / 07-08 15:07（使用者貼出 AI 建議跳過 diagnose））。maintainer 2026-07-26 表示「圖片看起來不好下載」，故不再追取。GitHub 端無 attachment（_manifest.json 為空）。

對本診斷的影響評估：根因（idd-plan frontmatter description 缺前置說明）是從 repo 內容機械查證得出的，不依賴任何圖片。圖片可能補強的是「使用者的 AI 當時確切說了什麼」的證據強度，但該 AI 建議的內容已由使用者以文字複述（15:06）。故判定：缺圖不影響根因判定與 Strategy，僅使 audit trail 略不完整。

Vagueness Pre-check

• V1 (vague WHAT): 2 — 診斷後 WHAT 已收斂為具名檔案與具名改動（skills/idd-plan/SKILL.md frontmatter 補 house pattern；generator 由 docs/workflows.md 產 mermaid 推 wiki），且兩個關鍵方向已由 maintainer 於 2026-07-26 拍板（採實作為準／自動生成），非開放式描述。
• V4 (vague ACCEPTANCE): 3 — Phase 1 的完成定義可機械判定（description 含 Use when: + 防止的失敗:；drift-guard assertion 通過）。Phase 2 部分留有未量化的門檻：「流程圖可讀」沒有客觀標準，31 條 path 要畫成一張還是多張未定，屬 mostly-clear 但非完全明確。
• Triggered: no — both axes ≤ 3（trigger 條件為任一軸 ≥ 4）

Sister Concerns Filed (mid-diagnose, v2.47.0+ #528)

依 feedback_systemic_prevention 紀律，把「skill description 漏寫硬前置」一般化成 class，掃過全部 12 個含 abort-marker 的 skill 的 frontmatter：

發現	判定	處置
idd-clarify description 同樣缺 Use when: / 防止的失敗: 字面形式	非正確性問題 —— 該 description 已明寫「Standalone primitive — also delegated by idd-issue Step 4.6, gated by idd-diagnose Step 0.5」，關係說清楚了，且設計上本就可獨立呼叫，沒有被省略的硬前置	不另開 issue。併入本 issue Phase 1：drift-guard assertion 的涵蓋範圍由「lifecycle skill」擴大為「所有 IDD skill」，idd-clarify 一併補齊 house pattern（同檔案模式、同修法、同 PR）
其餘 10 個含 abort-marker 的 skill（idd-all / idd-all-chain / idd-close / idd-comment / idd-diagnose / idd-find / idd-implement / idd-issue / idd-list / idd-verify）	description 皆含 Use when: 且前置關係與實作一致	無需行動

結論：本次 sister sweep 未產生新 issue（唯一發現已併入本 issue Phase 1 scope）。上一輪 /idd-issue Step 4.7 已 filed 的兩個 sibling（#277 Deep Research 整合、#278 reopen 路徑）狀態不變；兩者的結論若成立，應反映在 Phase 2 的同一張生成流程圖上。

Strategy 修正（因本 sweep 而擴大）：Phase 1 第三項的 drift-guard assertion 範圍由「每個 lifecycle skill」改為「每個 IDD skill」，並對有硬前置的 skill 額外斷言 description 須陳述該前置。

[kiki830621]

Implementation Plan (Plan tier)

Scope: 本 PR 只做 Diagnosis 的 Phase 1（機器面向根因 + 結構性防再犯）。Phase 2（generator + wiki 流程圖）不在本 PR，理由見 § Out-of-scope。

Plan 期間的範圍修正（誠實揭露）：Diagnosis 預估 Phase 1 只需改 idd-plan 一個 description。實際量測後是 5 個 skill 的 description 不符 house pattern，見下方 § Family-wide scope。這是 Plan tier approval gate 的價值所在 —— 差異在動手前被抓到，而不是 verify 才發現。

Files & Changes

• plugins/issue-driven-dev/scripts/tests/skill-description-contract/test.sh — 新增 drift-guard suite（先寫，RED）。逐一迭代 plugins/issue-driven-dev/skills/*/SKILL.md，對每個 skill 的 frontmatter description 斷言 A1–A4（見 § Test Plan）。形狀直接沿用既有 docs-catalog-sync/test.sh（fix: README gpt-5.5 pin + docs catalog drift (v2.97-2.99 backfill) — expand drift-guards to README/docs #267）的 pattern：. lib/assert-helpers.sh → for-loop → pass/fail → print_summary。runner run-all-tests.sh 以 for t in "$TESTS_DIR"/*/test.sh 自動發現，無需註冊
• plugins/issue-driven-dev/skills/idd-plan/SKILL.md — 根因所在。frontmatter description 補齊 house pattern，且必須明寫 diagnosis 前置。改動只在 frontmatter 三行內，body 不動
• plugins/issue-driven-dev/skills/idd-clarify/SKILL.md — 補 Use when: + 防止的失敗:（現有 description 內容正確、只缺 house pattern 字面形式）
• plugins/issue-driven-dev/skills/idd-comment/SKILL.md — 補 Use when:
• plugins/issue-driven-dev/skills/idd-all-chain/SKILL.md — 補 防止的失敗:
• plugins/issue-driven-dev/skills/idd-report/SKILL.md — 補 防止的失敗:
• plugins/issue-driven-dev/README.md — skill 表格 idd-plan 那列（:60）由 tier 光譜語彙（「sits between Simple and Spectra」）改為使用者語彙（誰觸發、何時觸發）。pipeline 圖（:52）不動 —— 它的修正依賴 Phase 2 的 wiki 頁存在
• plugins/issue-driven-dev/CHANGELOG.md — 新增 entry（Keep a Changelog 格式，Fixed + Added 兩節）

Family-wide scope

Diagnosis 的硬閘（#129）判 not triggered，依據是「預估 5 檔但含生成產物、無 shared abstraction」。Plan 期間的實測推翻了這個前提：本次的 shared abstraction 是「skill frontmatter description 的 house pattern」，其 family member = 所有不符規範的 skill。全 17 個 skill 實測：

Skill	缺 Use when:	缺 防止的失敗:	缺 diagnosis 前置
idd-plan	✗	✗	✗ ← 根因，三項全缺
idd-clarify	✗	✗	n/a（設計上 standalone）
idd-comment	✗	✓	n/a
idd-all-chain	✓	✗	n/a
idd-report	✓	✗	n/a
其餘 12 個	✓	✓	n/a 或已符合

5 個 family member 全部列入 in-scope（per #129 shared-abstraction 產出契約 / #44 教訓：Plan 只覆蓋觸發當下那一個、漏掉 sibling，要兩次 close 才補齊）。單一概念散佈 5 檔 ≥ 門檻 N=5，若在 diagnose 當下就知道這個數字，硬閘會觸發 —— 但出口仍是 Plan（sdd_bias 未設 → default），故 Complexity verdict 不變，僅補記觸發事實。

Sequencing & Dependencies

嚴格順序，不可並行：

1. 先寫 test.sh 並跑到 RED —— 必須先看到它對現況失敗（預期 8 個 fail：idd-plan×3 + idd-clarify×2 + idd-comment×1 + idd-all-chain×1 + idd-report×1）。跳過 RED 就無法證明 assertion 真的在測東西（本 repo 有前例：/idd-all-chain 設計缺陷: hard-coded cap=10 / 無 multi-root vs ripple-chain pre-flight / cap 超過時 silent truncate #119 的 Phase 0.4.5 是 placebo gate，三個 reviewer 才抓到）
2. 再改 5 個 description → 跑到 GREEN。順序上 idd-plan 先改（根因），其餘四個接著
3. 再改 README —— 它引用 idd-plan 的定位，措辭應與新 description 一致，故必須在 (2) 之後
4. 最後跑 run-all-tests.sh 全量 —— 確認新 suite 不與既有 39 個 suite 衝突（特別是 docs-catalog-sync 與 doc-sync-sweep，兩者同樣掃 skills/ 目錄）
5. CHANGELOG 最後寫（內容依實際落地結果）

Decision Points

D1 — assertion 範圍：repo-wide（17 skill）還是 lifecycle-only（6 skill）？
→ 選 repo-wide。 根因是「AI 讀 description 決定要跑哪個 skill」，這件事對 17 個 skill 一視同仁；只守 lifecycle 等於在 idd-comment / idd-report 留下同一個洞。代價是本 PR 多改 3 個檔案（idd-comment / idd-all-chain / idd-report），可接受。

D2 — 「哪些 skill 必須在 description 提 diagnosis 前置」怎麼判定：機械推導還是明列？
→ 選明列 allowlist（DIAGNOSIS_DEPENDENT=(idd-plan idd-implement)），並在 test.sh header 寫明為何不用推導。
證據：Plan 期間試過推導式 grep -l '先跑 \/idd-diagnose'，**會誤傷 idd-close** —— 該字串在 idd-close/SKILL.md:42出現，但語境是「meeting deliverable 兩者皆無時擋 close」的 fallback 提示，不是 close 自身的前置條件（close 的前置是 verify）。誤傷會逼idd-close` 的 description 寫入一個假前置。lifecycle graph 小且穩定，明列的維護成本低於誤判成本。

D3 — assertion 用字面比對（Use when / 防止的失敗）還是語意判定？
→ 選字面比對。 目的正是機器面向的表面一致性 —— 讓掃 description 的 AI 每次都在同一位置看到同一種訊號。語意判定無法在 bash drift-guard 內機械執行。cargo-cult 風險見 § Risks。

D4 — 版本號要不要在本 PR bump？
→ 不 bump。 依 repo 慣例版本 bump 屬 release 動作（common-release-flow.md）。本 PR 只寫 CHANGELOG 的 Unreleased/新版段落，實際 bump 與 marketplace sync 留給 release 流程。

Risks & Mitigations

Risk	Mitigation
Placebo gate —— test.sh 寫了但實際沒斷言到東西（本 repo #119 前例）	強制先跑 RED 並逐字記錄 8 個 fail 的名稱；GREEN 後再故意還原一個 description 確認會重新變 RED
Cargo-cult 字面比對（D3）—— 未來有人為了過測而塞一句無意義的 Use when: 需要時	assertion 只保證位置一致、不保證品質；在 test.sh header 明寫此限制，品質仍靠 review。與 docs-catalog-sync 的自述立場一致（「asserts MENTION, not quality」）
改 description 的行為 side effect —— description 是 AI 選 skill 的輸入，改動會影響所有使用者的路由	這正是目的。但新措辭須避免反向過度嚇阻：idd-plan 的新 description 要寫「diagnosis 確認且 Complexity 判為 Plan 之後」，不寫成讓 AI 以為 idd-plan 難用而永遠不選它
與既有 suite 衝突 —— docs-catalog-sync / doc-sync-sweep 同樣掃 skills/	新 suite 只讀 frontmatter、不改檔案、不共用 fixture 目錄；Sequencing 第 4 步跑全量驗證
17 個 skill 之外的未來 skill	assertion 用 glob 自動涵蓋新 skill —— 新增 skill 若不寫 house pattern 會立刻 RED。這正是「結構性防再犯」的實體

Test Plan

新 suite skill-description-contract，對每個 plugins/issue-driven-dev/skills/*/SKILL.md 的 frontmatter：

#	Assertion	RED 預期（改動前）	GREEN 預期（改動後）
A1	frontmatter 存在且含 description: 欄位	17/17 pass（sanity，本來就合規）	17/17 pass
A2	description 含 Use when	3 fail：idd-plan / idd-clarify / idd-comment	17/17 pass
A3	description 含 防止的失敗	4 fail：idd-plan / idd-clarify / idd-all-chain / idd-report	17/17 pass
A4	DIAGNOSIS_DEPENDENT allowlist 內的 skill，description 須 match diagnos	1 fail：idd-plan（idd-implement 已合規）	2/2 pass

RED 總計 8 個 fail。失敗訊息須指名補救方式（沿用 docs-catalog-sync 的 fail "$name" "說明 + 修法" 形式）。

回歸驗證：bash plugins/issue-driven-dev/scripts/run-all-tests.sh 全量通過（現有 39 suite + 新增 1）。

Out-of-scope (will NOT be touched)

• Phase 2 全部 —— generator（docs/workflows.md → mermaid）、wiki Workflow-Paths 頁、_Sidebar.md、README pipeline 圖（:52）與 wiki 連結。理由：(a) Diagnosis 的 Risks 已標「Phase 1 被 Phase 2 拖住」—— 根因只要改幾行 description，綁在同一 PR 等 generator 做完，錯誤路由會持續發生；(b) Phase 2 有三個未定的 decision point（解析契約 / 推送機制 / 31 條 path 的圖形呈現），Diagnosis 建議先跑 superpowers:brainstorming 對齊；(c) Phase 2 會寫入另一個 git repo（wiki），風險性質與本 PR 完全不同。docs: idd-plan ↔ idd-diagnose 的關係與順序未寫清楚 — 使用者與其 AI 都推論出「跳過 diagnose 直接 plan」 #276 不因本 PR 而 close
• idd-plan 的 hard abort 邏輯（SKILL.md:62）—— 2026-07-26 maintainer 授權裁決採實作為準，不放寬
• 其餘 12 個已合規 skill 的 description 措辭 —— 合規即不動，避免無謂 diff
• 版本號 bump 與 marketplace sync —— 見 D4
• feature: 決定 Claude Deep Research 與 IDD 的整合形狀（或明確宣告不整合 + 手動接法） #277 / docs: issue 已 closed 但事情還要做 — 缺 documented reopen / resume-implement 路徑 #278 —— 獨立 issue，各自走自己的 pipeline

Tangential Observations (filed mid-plan, v2.42.0+ #524)

none surfaced —— 兩個候選都經查證後判定為負，不 file：

候選	查證	判定
版本目錄字典序陷阱 —— Plan 期間我用 ls .../*/ | tail -1 找 plugin cache 最新版，拿到 2.99.1 而非實際最新的 2.101.0（字典序下 2.101.0 < 2.99.1）	grep 全部 shipped script：check-plugin-presence.sh:164 與 idd-verify/SKILL.md:193 都已正確使用 sort -V（後者甚至額外 grep -E '/[0-9]+\.[0-9]+\.[0-9]+/$' 排除 latest/current 目錄）	非 repo bug —— 是我本次 session 手動抄捷徑所致。repo 既有做法正確，無需行動
本 session 的 egress 走了舊 cache（2.99.1）	diff 兩版 gh-egress.sh：2.101.0 多一道 net #4（#272 reply tier-floor），只在 type=reply + points-from=user-pasted + attested light 時觸發；nets 1–3（home path / ~/.claude.json 內容 / #117 mention）兩版相同。本 session 全部 dispatch 皆為 create/edit/comment 且 attested warn	無實質影響 —— 沒有任何 dispatch 被少守。記錄於此供 audit，不需 file

（/idd-plan Step 2.5，IC_R011 mid-plan tangential sweep）