bug: idd-issue Step 1 (Source Type Adapter) 應在 MCP plugin 缺失時明確報錯 + 提示 install 指令 (sibling concern from #26)

[kiki830621]

Problem

Source: surfaced during /idd-issue #26 linked-context sister sweep (Step 4.7)

idd-issue Step 1 「Source Type Adapter」會依來源類型呼叫對應 MCP tool(mcp__che-word-mcp__get_document_text / mcp__plugin_che-telegram-mcp_* / mcp__plugin_che-apple-mail-mcp_* / mcp__plugin_che-apple-notes-mcp_*)。當該 MCP plugin 沒裝時:

• skill 不會明確報「請先 claude plugin install che-word-mcp@...」
• 只會 fallback 到請使用者手動處理(Telegram fallback) 或 silently 用其他工具讀取
• 使用者誤以為 IDD 不支援該格式,而不是少裝一個 plugin

Type

bug (UX / error-reporting)

Expected

Step 1 Source Type Adapter 在偵測到來源是 .docx / Telegram / Mail / Notes 時:

1. 先檢查對應 MCP tool 是否存在(從 ToolSearch 或 deferred tool list 確認)
2. 不存在 → 明確報錯 + 給出 install 指令範本:

   ✗ 此來源是 .docx,需要 che-word-mcp plugin。
     請先安裝:claude plugin install che-word-mcp@<marketplace>
     或改貼純文字內容到 prompt。
   

3. 存在 → 照原邏輯走

Actual

skill description 假設所有 MCP tool 都已可用,fallback 寫成「使用者手動操作」或 silent fall-through。

Impact

• Onboarding 卡點:同 docs: README 應列出 issue-driven-dev 仰賴的外部 plugin / MCP server (依 source type) #26 列出的 onboarding 痛點,但發生在 skill execution 時(更晚被發現)
• 誤導性錯誤:使用者得到「此格式不支援」的錯印象,實際只是 plugin 沒裝
• 與 docs: README 應列出 issue-driven-dev 仰賴的外部 plugin / MCP server (依 source type) #26 互補:docs: README 應列出 issue-driven-dev 仰賴的外部 plugin / MCP server (依 source type) #26 是「事前 docs 標明依賴」,本 issue 是「事中錯誤訊息明確指引」

Related

• docs: README 應列出 issue-driven-dev 仰賴的外部 plugin / MCP server (依 source type) #26 (docs side)

Priority: P3 (UX 改善,非 blocker)

Current Status

Phase: closed
Last updated: 2026-05-07 by idd-close

Resolution

• PR cluster: #27 source-type adapter fail-fast + #34 generic plugin-presence helper (Plan tier) #39 merged → main
• cluster with refactor: 抽出 generic plugin-presence detector helper (tangential from #28 plan) #34 — Step 1 MCP plugin presence pre-flight + structured fail-fast (per docs: spec 出 #27 fail-fast 訊息實際長相 (sister from #26) #32 absorbed spec)

[kiki830621]

Acceptance Criteria Refinement (absorbed from #32)

Source: refined from #32 (closed, content absorbed here for canonical reference)
Related: #26 (where this concern first surfaced during README documentation)

#27 原本只說「明確報錯 + 提示 install 指令」沒規定 error message 長什麼樣。以下是具體 spec,implement 時請以本段為驗收標準。

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(verify 時必須符合)

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

Cross-references

• plugins/issue-driven-dev/README.md#requirements 已含 marketplace 對照表(由 docs: README 應列出 issue-driven-dev 仰賴的外部 plugin / MCP server (依 source type) #26/docs: README install 指令的 <your-marketplace> placeholder 缺 lookup hint (sister from #26) #31 提供) — fail-fast 訊息應 link 過去
• 「lookup hint」對應 docs: README install 指令的 <your-marketplace> placeholder 缺 lookup hint (sister from #26) #31 在 README 加的 claude plugin marketplace list block

Priority: P3 (#27 內可 implement,本 acceptance criteria 直接套用)

[kiki830621]

Diagnosis (cluster with #34)

Type

bug (UX / error-reporting) — refactored from #28 helper pattern via #34

Analysis

#27 提出 idd-issue Step 1 Source Type Adapter 在 MCP plugin 缺失時應 fail-fast + 提示 install 指令。#32 已 absorb 入 #27 提供具體 error format spec (3-option block, structured stderr message)。#34 提議從 #28 抽 generic helper。

Cluster decision (#27 + #34 一起做): refactor 是自然 emergence 而非預先 abstraction —#28 已寫了 1 個 detect helper, #27 implement 即將寫第 2 個 detect helper (4 source-type MCP plugins),滿足 IDD「3 instance 才抽 abstraction」邊界(2 instance 足夠看出 pattern,且 #34 已 file 為 explicit refactor candidate)。

Strategy (cluster-PR, single branch)

• Refactor (refactor: 抽出 generic plugin-presence detector helper (tangential from #28 plan) #34) — abstract scripts/check-plugin-presence.sh
  • Generic 版本接受 <marketplace> <plugin-name> 參數
  • 維持 nullglob + bash array pattern (F3 fix from feature+docs: idd-verify --loop / idd-all unattended 隱性依賴 ralph-loop — 應宣告 + auto-detect + 內建探索 #28 verify)
  • IDD_SKIP_PLUGIN_CHECK env var (取代 IDD_SKIP_RALPH_CHECK)
  • 同樣的 stderr warning + install hint format
• Migrate (refactor: 抽出 generic plugin-presence detector helper (tangential from #28 plan) #34) — scripts/check-ralph-loop.sh 變成 wrapper
  • 1-line wrapper: exec "$(dirname "$0")/check-plugin-presence.sh" claude-plugins-official ralph-loop "$@"
  • 保留 backward compat (idd-verify Step 0a + idd-all Phase 0.6 不需改)
• Implement (bug: idd-issue Step 1 (Source Type Adapter) 應在 MCP plugin 缺失時明確報錯 + 提示 install 指令 (sibling concern from #26) #27) — idd-issue Step 1 Source Type Adapter fail-fast
  • 在 4 source type case (.docx / Telegram / Apple Mail / Apple Notes) 入口 invoke check-plugin-presence.sh <marketplace> <plugin>
  • Missing → print structured error (per docs: spec 出 #27 fail-fast 訊息實際長相 (sister from #26) #32 spec):明確 cause + 3 options + abort
  • 4 messages 結構一致,只差 plugin name + marketplace
  • 直接貼純文字 / .md 不 trigger detect (no plugin needed)

Files to change

File	Change	Issue
plugins/issue-driven-dev/scripts/check-plugin-presence.sh (NEW)	generic helper	#34
plugins/issue-driven-dev/scripts/check-ralph-loop.sh	refactor to wrapper	#34
plugins/issue-driven-dev/skills/idd-issue/SKILL.md	Step 1 Source Type Adapter 加 detect calls + structured error	#27

Complexity

Plan

• ✅ 2+ files 順序依賴 (helper 先 / wrapper 後 / idd-issue 用 helper)
• ✅ Decision-heavy:keep check-ralph-loop.sh as wrapper vs delete + 改 idd-verify/idd-all → 選 wrapper(backward compat,已 merged 6aec214)
• ✅ Risk-sensitive:Bundle 共用 helper,helper 改錯會同時 break feature+docs: idd-verify --loop / idd-all unattended 隱性依賴 ralph-loop — 應宣告 + auto-detect + 內建探索 #28 (idd-verify --loop) 和 bug: idd-issue Step 1 (Source Type Adapter) 應在 MCP plugin 缺失時明確報錯 + 提示 install 指令 (sibling concern from #26) #27 (idd-issue 4 source types)
• ✅ Cross-file refactor with no external API change (helper 是 internal)

但本 diagnose 已明確 strategy + decisions,可以借 user trust skip /idd-plan EnterPlanMode(同 #11 模式)— Plan tier deliberation 已在 diagnose 完成。

Risks

• High: helper 改錯會 cascade break feature+docs: idd-verify --loop / idd-all unattended 隱性依賴 ralph-loop — 應宣告 + auto-detect + 內建探索 #28 paths。Mitigation:test 4 cases — generic helper installed/missing × env-var bypass yes/no
• Medium: idd-issue Step 1 加 detect logic 太重 — 4 source type 各加 detect call,maintenance load。Mitigation:單 helper file,Step 1 prose 用 inline 1-liner per type
• Low: check-ralph-loop.sh wrapper 增加 1 layer indirection,bash invocation 開銷 negligible

Related

• feature+docs: idd-verify --loop / idd-all unattended 隱性依賴 ralph-loop — 應宣告 + auto-detect + 內建探索 #28 (parent — provides the original check-ralph-loop.sh pattern)
• docs: spec 出 #27 fail-fast 訊息實際長相 (sister from #26) #32 (absorbed into bug: idd-issue Step 1 (Source Type Adapter) 應在 MCP plugin 缺失時明確報錯 + 提示 install 指令 (sibling concern from #26) #27 — provides error format spec)
• docs: README 應列出 issue-driven-dev 仰賴的外部 plugin / MCP server (依 source type) #26 (great-parent — surfaced this concern)

[kiki830621]

Implementation Complete (cluster-PR for #27 + #34)

Checklist (synced)

• refactor: 抽出 generic plugin-presence detector helper (tangential from #28 plan) #34 refactor: scripts/check-plugin-presence.sh (NEW generic) → commit b6d97bc
• refactor: 抽出 generic plugin-presence detector helper (tangential from #28 plan) #34 backward-compat: scripts/check-ralph-loop.sh 變 wrapper(舊 IDD_SKIP_RALPH_CHECK=1 仍 honored) → commit b6d97bc
• bug: idd-issue Step 1 (Source Type Adapter) 應在 MCP plugin 缺失時明確報錯 + 提示 install 指令 (sibling concern from #26) #27 fail-fast: idd-issue/SKILL.md Step 1 加 MCP plugin presence pre-flight + structured error (per docs: spec 出 #27 fail-fast 訊息實際長相 (sister from #26) #32 absorbed acceptance criteria) → commit c7f23bf

Legend: - [x] done

Self-verify

• ✓ generic helper 4-case smoke test PASS:installed (exit 0) / missing (exit 1) / IDD_SKIP_PLUGIN_CHECK=1 + missing (exit 0 + warning) / usage error (exit 2)
• ✓ wrapper backward-compat:bash check-ralph-loop.sh 仍 work,legacy IDD_SKIP_RALPH_CHECK=1 env var 透過 wrapper export 為 IDD_SKIP_PLUGIN_CHECK=1
• ✓ idd-issue Step 1 4-row case statement 涵蓋 .docx / Telegram / Apple Mail / Apple Notes
• ✓ structured error message format 對齊 docs: spec 出 #27 fail-fast 訊息實際長相 (sister from #26) #32 absorbed spec
• ✓ README marketplace 對照表 row (psychquant-claude-plugins) 與 helper 引用 marketplace name 一致 (docs: README install 指令的 <your-marketplace> placeholder 缺 lookup hint (sister from #26) #31 fix prevented mismatch)

Changes (cluster, 3 files)

• b6d97bc refactor: 抽出 check-plugin-presence.sh generic + check-ralph-loop.sh 變 wrapper (refactor: 抽出 generic plugin-presence detector helper (tangential from #28 plan) #34)
• c7f23bf feat: idd-issue Step 1 MCP plugin presence pre-flight + structured fail-fast (bug: idd-issue Step 1 (Source Type Adapter) 應在 MCP plugin 缺失時明確報錯 + 提示 install 指令 (sibling concern from #26) #27)

Files Changed

 .../scripts/check-plugin-presence.sh               | 72 ++++++++++++++++++++++
 .../issue-driven-dev/scripts/check-ralph-loop.sh   | 58 +++++------------
 plugins/issue-driven-dev/skills/idd-issue/SKILL.md | 50 +++++++++++++++
 3 files changed, 136 insertions(+), 44 deletions(-)

Scope Compliance

• ✅ 3 file change 對齊 cluster diagnose Strategy
• ✅ Backward compat preserved (feature+docs: idd-verify --loop / idd-all unattended 隱性依賴 ralph-loop — 應宣告 + auto-detect + 內建探索 #28 existing callers unchanged)
• ✅ Marketplace name psychquant-claude-plugins (per docs: README install 指令的 <your-marketplace> placeholder 缺 lookup hint (sister from #26) #31 verify-fix learning)

Next: verification pending (lightweight self-verify done; full 6-AI not used since refactor is mechanical + reuses #28 verified pattern)

[kiki830621]

Closing Summary (cluster #27 with #34)

Problem

idd-issue Step 1 Source Type Adapter 在 MCP plugin 缺失時靜默 fallback("讓使用者手動處理")或誤用其他 tool,使用者誤以為 IDD 不支援該格式 (.docx / Telegram / Apple Mail / Apple Notes),不知道是少裝 plugin。

Root Cause

Step 1 SKILL.md 寫了 4 row Source Type Adapter table 標明每種 source 對應的 MCP tool,但沒寫缺失時的 detect + abort logic。Silent fallback 違反 IDD「不靜默」紀律。

#32 absorb 入 #27 提供具體 error message format spec(明確 cause + 3 options + abort),否則 acceptance 無法驗證。

Solution

Cluster-PR with #34 (generic helper refactor):

#27 part: idd-issue/SKILL.md Step 1 加 #### MCP plugin presence pre-flight sub-section,4 source-type case 各自 invoke check-plugin-presence.sh(#34 提供的 generic helper) detect → missing 則 print structured error per #32 spec + abort:

✗ Source detected as <SOURCE_DESC> but `<PLUGIN>` MCP plugin is not installed.

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

Options:
  1) Install plugin (recommended): claude plugin install <PLUGIN>@<MARKETPLACE>
  2) Convert to another supported format (.md / .txt / image)
  3) Manual fallback (not recommended for archives)

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

直接貼純文字 / .md 不 trigger detect (no plugin needed)。

Verification

Lightweight self-verify PASS:

• Section placement (Step 1 Source Type Adapter 之後、Telegram 專屬流程之前)
• 4-row case statement 涵蓋 .docx / Telegram / Apple Mail / Apple Notes,marketplace 對齊 psychquant-claude-plugins
• Structured error message 格式對齊 docs: spec 出 #27 fail-fast 訊息實際長相 (sister from #26) #32 absorbed spec
• Refactor reuses feature+docs: idd-verify --loop / idd-all unattended 隱性依賴 ralph-loop — 應宣告 + auto-detect + 內建探索 #28 verified helper pattern + refactor: 抽出 generic plugin-presence detector helper (tangential from #28 plan) #34 generic abstraction

Changes

• c7f23bf feat: idd-issue Step 1 加 MCP plugin presence pre-flight + structured fail-fast (Refs bug: idd-issue Step 1 (Source Type Adapter) 應在 MCP plugin 缺失時明確報錯 + 提示 install 指令 (sibling concern from #26) #27)
• 77d7efe (squash on main) cluster PR cluster: #27 source-type adapter fail-fast + #34 generic plugin-presence helper (Plan tier) #39 merged

Related (cluster)

• refactor: 抽出 generic plugin-presence detector helper (tangential from #28 plan) #34 (paired refactor — generic helper that this issue uses)
• feature+docs: idd-verify --loop / idd-all unattended 隱性依賴 ralph-loop — 應宣告 + auto-detect + 內建探索 #28 (great-parent — provides original detector pattern)
• docs: spec 出 #27 fail-fast 訊息實際長相 (sister from #26) #32 (absorbed — provided error format acceptance criteria)
• docs: README 應列出 issue-driven-dev 仰賴的外部 plugin / MCP server (依 source type) #26 (great-great-parent — surfaced this concern via sister sweep)