[design] Document 'surfacing-only primitive' skill family pattern (idd-list / idd-clarify / future idd-find?) (sibling concern from #139)

[kiki830621]

Problem

從 #139 sister sweep 浮出:IDD plugin 出現一個尚未明文化的 design pattern family — "surfacing-only primitive":輕量 read-only skill,augments 主 pipeline (issue → diagnose → implement → verify → close) 但不參與 lifecycle phase 流程。

目前 family member:

• /idd-list (v2.51.0+) — structural triage (state / label / phase / PR cluster)
• /idd-clarify ([META][idd-issue] terminology trust gap — source 用錯 domain term 時 AI 繼承錯誤 #135, v2.72.0+) — terminology / semantic accuracy axis (third axis alongside IC_R010 Confidence + IC_R007 Verbatim)
• /idd-find (feature: /idd-find — semantic search for IDD-aware related issues across open+closed corpus #139 proposal,若 Option A 採納) — semantic search across open+closed corpus

共同特徵:

1. Read-only:不 mutate state (no gh issue create / gh issue edit / gh issue close)
2. Standalone runnable:可任何時候 invoke,不需 in-flight phase context
3. Delegate-able:其他 skill 可內嵌呼叫(idd-clarify 已 delegated by idd-issue Step 4.6 + gated by idd-diagnose Step 0.5)
4. Augmentation not replacement:擴展既有 pipeline,而非取代

family 還未文件化,未來 add 第 4 個 primitive 時容易:

• 重複設計同類 boilerplate (Step 0 bootstrap / config protocol / unattended fallback / --cwd flag)
• 跟既有 lifecycle skill 混淆 (例如不小心讓 surfacing primitive 寫 state)
• Skill 數量爆炸 (cognitive cost),沒系統性 review 「該不該抽 family」

Type

design / docs(architectural pattern documentation)

Expected

Document the surfacing-only primitive family pattern,例如新 reference doc references/surfacing-primitives.md 或 docs/skill-dimensions.md 新 axis "D12 Surfacing vs Lifecycle":

Axis	Surfacing-only	Lifecycle
是否 mutate state	❌ read-only	✅ writes to GitHub / git
是否參與 phase	❌ orthogonal	✅ advances issue.phase
Invocation context	standalone or delegated	usually within pipeline order
Existing members	idd-list / idd-clarify / (idd-find?)	idd-issue / idd-diagnose / idd-implement / idd-verify / idd-close

加 D12 後,加新 primitive 前先過 axis review:「這個 skill 該 surfacing 還 lifecycle?」

Actual

無 explicit pattern documentation。/idd-clarify 在 README:45 行 description 自描為「surfacing-only primitive」,但這個詞沒任何 anchor 解釋它代表什麼 family 共識。未來 contributor / maintainer 讀到不知道 implied 設計 contract。

Open questions

1. Pattern 命名:「surfacing-only primitive」夠精準嗎?有更好的名稱嗎?
2. 是否需要 family: surfacing 在 SKILL.md frontmatter 標示,讓 tooling 能 enumerate?
3. /idd-find 若採 Option C (extend /idd-list) 而非 Option A,family member 就停在 2 個,pattern 抽象化是 premature。待 feature: /idd-find — semantic search for IDD-aware related issues across open+closed corpus #139 diagnose 後再 decide 是否實際 file pattern doc。

Source

surfaced during /idd-issue #139 linked-context sister sweep (Step 4.7)

---

Current Status

Phase: diagnosed
Last updated: 2026-07-11 by /idd-diagnose (via /idd-all focused batch drain)

Key Decisions

• 維持 parked — blocked on feature: /idd-find — semantic search for IDD-aware related issues across open+closed corpus #139 裁決（family 第 3 員未定，動工即 premature abstraction）

[kiki830621]

Diagnosis

Type

design / docs（architectural pattern documentation — surfacing-only primitive family）

Root Cause / Analysis

Pattern 真實存在（idd-list / idd-clarify 共享 read-only、standalone、delegate-able、augmentation 四特徵），但 issue 自身的 open question 3 已把成案前提綁在 #139 的裁決：若 idd-find 走 Option C（extend idd-list），family 停在 2 個成員，抽象化即 premature（rule-of-three 未過）。查證：#139 目前仍 OPEN 未裁決 → 本案前提未成立。

Impact

（若 triggered）新 reference doc references/surfacing-primitives.md 或 skill-dimensions D12 軸 — 純文件。

Strategy

• [~] 暫緩實作 — deferred: 等 feature: /idd-find — semantic search for IDD-aware related issues across open+closed corpus #139 裁決（Option A → family 第 3 員成立 → 動工；Option C → family=2，收斂為 README 一句 pattern 註記或 close won't-fix）
• feature: /idd-find — semantic search for IDD-aware related issues across open+closed corpus #139 裁決後重評本案（trigger 記錄於此）

Conflict Class

D_diagnose_first → 診斷完成，re-bucket 為 parked（blocked on #139）。

Complexity

Simple when triggered

Layer 1 命中（純 pattern 文件，narrative deliverable）。Hard-gate: not triggered — 單一新文件。當前處置 = parked：前提（#139 裁決）未滿足，動工即 premature abstraction。

Risks

• feature: /idd-find — semantic search for IDD-aware related issues across open+closed corpus #139 長期未裁決 → 本案永久懸置；可接受（pattern 未文件化的代價 = 低，兩個現成員的 README 描述已部分覆蓋）

Residue

「family 該不該有 frontmatter 標示（open question 2）」依附主決策，不獨立成案。

Vagueness Pre-check

• V1: 2 — deliverable 清楚，唯前提未成立
• V4: 3 — 完成邊界依 feature: /idd-find — semantic search for IDD-aware related issues across open+closed corpus #139 選項而定
• Triggered: no

[Layer V: V1=2 V4=3, not triggered; unattended mode]

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

(none)

---

Source: /idd-all focused batch drain (unattended), 2026-07-11 — 診斷結論：維持 parked，blocked on #139