docs: spec 出 #27 fail-fast 訊息實際長相 (sister from #26)

[kiki830621]

Refinement of #27

Source: surfaced during /idd-implement #26 reproduction (Step 5.7)

#27 提出 idd-issue Step 1 在 MCP plugin 缺失時應該明確報錯 + 提示 install 指令,但沒指定錯誤訊息應該長什麼樣。

#26 implement 過程在 plugin README 寫「該 source type 會被迫 fallback 到使用者手動處理」時,意識到 fallback 訊息本身應該是 #27 的具體 acceptance criteria 之一 — 不能只說「明確報錯」,要規定 error format 才能驗收。

Suggested error format spec

當使用者餵 .docx 給 /idd-issue 但 che-word-mcp 不存在時:

✗ Source detected as `.docx` but `che-word-mcp` MCP plugin is not installed.

該 source type 需要對應 MCP plugin 才能讀取文字 + 抽圖。

Options:
  1) Install plugin (recommended):
     claude plugin install che-word-mcp@<your-marketplace>
     # 不知 marketplace? 跑: claude plugin marketplace list
     # 詳見: plugins/issue-driven-dev/README.md#optional-per-source-type

  2) Convert to another supported format:
     - Save as `.md` or `.txt` then paste content directly
     - Or screenshot then attach as image (如果 docx 主要內容是 figures)

  3) Manual fallback (not recommended for archives):
     paste relevant text into prompt directly

Aborting /idd-issue. Run again after installing or converting.

對其他 source type (Telegram / Mail / Notes) 套類比結構。

Acceptance criteria 加入 #27

• Error message 格式如上(明確 cause + 3 options + abort)
• Options 用編號列表,不是 prose
• Install command 用 placeholder + 同時附 lookup hint
• 不同 source type 訊息結構一致(便於使用者建立 mental model)

Related

• bug: idd-issue Step 1 (Source Type Adapter) 應在 MCP plugin 缺失時明確報錯 + 提示 install 指令 (sibling concern from #26) #27 (parent — 本 issue 是其 acceptance criteria refinement)
• docs: README 應列出 issue-driven-dev 仰賴的外部 plugin / MCP server (依 source type) #26 (where this concern surfaced)

Priority: P3 (與 #27 同 priority,可一起 implement)

Current Status

Phase: closed (absorbed into #27)
Last updated: 2026-05-07 by absorb-and-close pattern

Resolution

• Spec content posted as refinement comment to bug: idd-issue Step 1 (Source Type Adapter) 應在 MCP plugin 缺失時明確報錯 + 提示 install 指令 (sibling concern from #26) #27 (bug: idd-issue Step 1 (Source Type Adapter) 應在 MCP plugin 缺失時明確報錯 + 提示 install 指令 (sibling concern from #26) #27 (comment))
• No code change — meta-issue refinement only
• bug: idd-issue Step 1 (Source Type Adapter) 應在 MCP plugin 缺失時明確報錯 + 提示 install 指令 (sibling concern from #26) #27 implement 將以本 issue 提供的 spec 為 acceptance criteria

Why no PR

/idd-all Phase 0.5 abort:#32 deliverable 是 #27 body 的 acceptance criteria 補強,不是 codebase 改動。走 PR pipeline 過度工程。改用 idd-comment 模式 absorb to #27 + close。

[kiki830621]

Closing Summary

Problem

#32 是「補 #27 acceptance criteria 詳細程度」的 meta-issue refinement,不是獨立的 code change。

Root Cause

原 #27 只說「明確報錯 + 提示 install 指令」沒規定 error message 格式 — 沒 spec 等於沒 acceptance criteria,將來 verify 無從判斷。本 issue (#32) 由 #26 implement Step 5.7 sister sweep 浮現,提供具體 error format spec。

Solution

Absorb-and-close: 把 #32 的 spec 內容(error message format + 4 條 acceptance criteria)以 refinement comment 形式 post 到 #27 (https://github.com/PsychQuant/issue-driven-development/issues/27#issuecomment-4393319458),作為 #27 的 canonical acceptance criteria reference。#27 implement 時直接照該 spec 寫即可。

Verification

無 code 改動 — 純 issue body / comment 操作。Verification 在 #27 implement 完成時做(verify 必須符合 4 條 acceptance criteria 的 checkbox)。

Changes

• 無 commit (此 issue 是 issue-tracker-only refinement)
• Refinement comment posted to bug: idd-issue Step 1 (Source Type Adapter) 應在 MCP plugin 缺失時明確報錯 + 提示 install 指令 (sibling concern from #26) #27: bug: idd-issue Step 1 (Source Type Adapter) 應在 MCP plugin 缺失時明確報錯 + 提示 install 指令 (sibling concern from #26) #27 (comment)

Why no implement / no PR

按 idd-all 啟動後 diagnose 發現:#32 的 deliverable 是 #27 body 的 acceptance criteria 補強,不是 codebase 改動。走完整 idd-all PR pipeline (feature branch + PR review + verify + close) 等於為「補 issue body」開 PR,過度工程。
正確路徑是 idd-comment 模式: post refinement to #27 + close #32 with absorption note。

Follow-ups

• bug: idd-issue Step 1 (Source Type Adapter) 應在 MCP plugin 缺失時明確報錯 + 提示 install 指令 (sibling concern from #26) #27 (parent — 待 implement 時依本 spec 為準)
• feature+docs: idd-verify --loop / idd-all unattended 隱性依賴 ralph-loop — 應宣告 + auto-detect + 內建探索 #28 (Layer 1 重組頂層 README mode-required dependency,獨立 issue)