[META][idd-issue] terminology trust gap — source 用錯 domain term 時 AI 繼承錯誤

[kiki830621]

[kiki830621]

Design discussion(2026-05-21 dialogue summary)— idd-clarify 應為獨立 skill

User feedback(LINE 對話):「diagnose 是承認 issue 的情況下去做的事情」— 直接定義了 clarify 跟 diagnose 的 boundary。

Core insight

IDD skill graph 有三個 orthogonal axis,本 issue 補的是缺的第三軸:

Axis	Existing safeguard	Skill
Confidence(客戶是否真的反映)	IC_R010 / Step 4.4	idd-issue Step 4.4 + idd-diagnose Step 3.4
Verbatim(原文是否被改寫)	IC_R007	source preservation in idd-issue Step 1
Terminology / Semantic accuracy(source 用詞是否正確,需求是否完整)	無	idd-clarify(新)

idd-diagnose 的前提:issue description 是正確的,只需 routing + complexity 分類。若描述本身有誤(domain term wrong / 隱含假設未說明 / 缺資料來源規格),diagnose chain 會繼承錯誤越走越歪。Clarify 必須在 diagnose 之前獨立成 skill。

Skill chain placement

idd-issue (file)
    ↓
idd-clarify (semantic audit) ← 新增,independent skill
    ↓
idd-diagnose (routing + complexity, assumes issue is now correct)
    ↓
idd-plan / idd-implement / idd-verify / idd-close

也可以不 chain — idd-clarify #N 對既存 issue 跑 retrospective audit(半年後 issue review、cluster audit 一輪 source-doc 等)。

What idd-clarify does

對 target issue body 做三層 audit:

Layer	Detect	Example (#804 case)
Terminology	source domain term + AI canonical 不符	「特徵值」+ K-means context → 提議「分群變數 / distinguishing variable」
Ambiguity	同一概念多歧義	「分群」沒指明 unsupervised(K-means) vs supervised(classification)
Missing context	分析需要 X 但 source 未指定	df_qef_customer_attributes(customer × variable × score)分析需要,issue 未指定來源(AI scoring / 問卷 / derivation?)

Surface mechanism

每個 finding 三選一 AskUserQuestion:

• Accept clarification → PATCH issue body(原文 blockquote 保留,加 Canonical 註解)
• Defer → 加標記不改 body
• Dismiss → false positive,記錄使用者 override(避免下次 re-run 又跑出來)

Missing-context findings 額外 4th option:spawn sister issue 釐清(user confirm 後 gh issue create)。

Audit trail

PATCH 既存 issue body 加 section:

### Clarifications Applied(idd-clarify run YYYY-MM-DDTHH:MM:SSZ)

| Source phrase | Audit type | AI canonical | User decision |
|---|---|---|---|
| 特徵值 | terminology | 分群變數 / distinguishing variable | accept (body uses canonical, blockquote retains 特徵值) |
| customer × attribute scores 來源 | missing-context | 規格 gap | spawn sister #N to ask 老師 |

Downstream effect

idd-diagnose / idd-plan / idd-implement 讀 Clarifications section,在自己的 output 中 SHALL use canonical term(不用 source 原詞)。Original source blockquote 仍 verbatim retained per IC_R007。

Heuristic library

需要 canonical-term lookup:領域(統計 / ML / clustering / regression / Bayesian / classification / dimensionality reduction / 商業分析 / medical / legal)→ common-misuse pattern。建議放 references/terminology-canonical.md,可由 maintainer 漸進擴充(rule of three:同樣的 misuse 出現 3 次升格進 library)。

Open questions(待 maintainer 決定)

1. idd-clarify 是否自動觸發於 idd-issue 之後? 或純手動 / idd-diagnose 觸發?
   • Pro auto:user 不會忘
   • Con auto:每個 issue 多一輪 prompt,輕量 issue 很煩
   • 建議:auto-on for document-source issues(.docx / .pdf,domain-term-heavy),manual for pasted-text(usually internal terminology already correct)
2. 跟 spectra-discuss 的關係 — 兩者都做「想清楚」,但 spectra-discuss 範圍更廣(design / requirement / architecture),idd-clarify 範圍窄(issue 本體 semantic correctness)。建議 cross-link 不重疊。
3. Domain library 維護權:maintainer 自填 or 開放 contribution PR?
4. 跟 IC_R007 verbatim preservation 紀律的邊界 — clarify 改 body 不改 blockquote,但若 user 強烈要求改原文 quote(極罕見)該允許嗎?建議:禁止改 blockquote,clarify 只加註,不覆蓋(避免 audit trail 斷裂)。

Concrete trigger:本次 #804 incident

老師 LINE 對話 2026-05-21 21:25-21:29:

「我以為你懂」「應該是說分群變數」「很多都沒有分群變數」

證實:source 用「特徵值」非客戶刻意挑詞,而是術語不精確。AI 這次運氣好(K-means context canonical 自動修對),但未來不同 domain combo 未必。

→ idd-clarify 在 idd-issue 完成後強制(for doc source)跑一次,把這種隱性 mismatch surface 給人類 review,是 reliability 必要環節。

---

Maintainer action(if accepting this design):

1. 把本 issue [META][idd-issue] terminology trust gap — source 用錯 domain term 時 AI 繼承錯誤 #135 重新 frame 為「idd-clarify skill 新增」實作 issue
2. 開 openspec/changes/add-idd-clarify-skill/ spectra change
3. Heuristic library references/terminology-canonical.md 初版列 #804 captured patterns(K-means/特徵值/PCA/regression/Bayesian 等)
4. Decide auto-trigger vs manual(建議 hybrid:doc source auto, paste manual)

[kiki830621]

Design iteration — primitive + orchestrator pattern

User feedback chain(LINE + Claude Code session 2026-05-21 ~ 2026-05-22):

Iteration	Frame	Critique 抓到的洞
v0 (my初版)	獨立 skill /idd-clarify with AskUserQuestion + PATCH body resolution flow	失職 gatekeeper 問失職 gatekeeper paradox — 沒 oracle 時 user 就是 over-worked filter,問他等於問空氣
v1 (my retry)	塞進 idd-diagnose 當 sub-step,surfacing-only no resolution	diagnose 預設 issue 對 — 把 State 1(問題是否 framed correctly)塞進 State 2(怎麼解)= category error / paradox
v2 (my retry)	idd-issue Step 4.8 Clarity Surface,跟 4.4 / 4.7 並列 advisory	lose retroactive case + clarify logic 跟 idd-issue 耦合 → 未來 reuse 困難
v3 (final)	/idd-clarify primitive + idd-issue Step 4.8 auto-invokes(composable orchestrator pattern)	這個對了

v3 final design

/idd-clarify <#N>                  ← standalone primitive (retroactive-friendly)
    ↑ delegated by
idd-issue (Step 4.8 auto-invoke)   ← orchestrator (zero UX burden, called at end of filing)
    ↑ gated by
idd-diagnose (Step 0.5 PR Gate)    ← refuses to run if Clarity Surface has unresolved rows

Why composable beats inlined Step 4.8

面向	Inlined Step 4.8(v2)	Composable primitive(v3)
Single source of truth	clarify logic 跟 idd-issue 耦合;若未來 idd-edit / idd-update 也要 clarify,複製代碼	只活在 /idd-clarify SKILL.md
Retroactive case	要加 idd-issue --reclarify #N flag(怪)	/idd-clarify #N 天然就是 retroactive
未來 chainable	idd-issue 之外的 caller 要 inline 整段	任何 skill 都能 delegate(SHALL invoke /idd-clarify discipline)
Maintenance drift	高(兩個地方要 sync)	低(一處改全部受惠)
UX	同(都是 auto-on,user 不用記額外命令)	同

類比 Unix:git commit 自動跑 pre-commit hook,但 hook 也獨立 runnable;make build 內部叫 make compile,compile 自己也是 target。這是 skill graph 的 composability 升級,不只是「多一個 skill」。

Surfacing-only contract(carries over from v2)

/idd-clarify 不做 resolution:

• 不 AskUserQuestion(沒 oracle 假設)
• 不 PATCH source blockquote(IC_R007 verbatim preservation)
• 只在 issue body 加 annotation:

### Clarity Surface(idd-clarify run 2026-05-22T05:00:00Z)

| Type | Source | Suggested canonical | Status |
|---|---|---|---|
| terminology | 「特徵值」(K-means context) | 分群變數 / distinguishing variable | surfaced — unresolved |
| missing-context | customer × attribute scores 來源 | spec gap | surfaced — needs upstream clarification |

Status 三態:surfaced / dismissed / resolved。預設 surfaced,user 可後續手動或重跑 /idd-clarify #N --status resolved=row-N 之類更新。

Downstream gate behavior

idd-diagnose Step 0.5 加 check:

unresolved_count = grep_clarity_surface(issue_body, status="surfaced")
if unresolved_count > 0:
    REFUSE diagnose with message:
      "Issue #N has N unresolved Clarity Surface rows. Resolve via:
        - /idd-clarify #N --status resolved=<idx>  (記錄 user judgment)
        - /idd-clarify #N --status dismissed=<idx> (記錄 false positive + reason)
        - LINE/email domain expert and update issue body manually"

類比 PR Gate Check pattern(unmerged PR refuses issue close)。強制 surface 不忽略,但不強制特定答案。

Recursive evidence

本 session 在 IDD design 上連 3 輪推到太抽象的解(獨立 skill → diagnose sub-step → idd-issue inline step),user 連 3 輪 push back 切到更細顆粒,最後降到 composable primitive。這正好證明 /idd-clarify 自己需要存在:AI 在 design 階段也會 over-abstract,需要 third-party surfacing 機制把「這個 abstraction 真的對嗎?」帶到 review surface。Maintainer reviewing 本 issue 時,本 session conversation 自己就是 case study。

Open questions for maintainer

1. Auto-trigger scope on idd-issue Step 4.8:doc source 全跑 / pasted-text 也跑 / 純 --multi-finding mode 跳過?(目前 source preservation 紀律不一致,Step 4.7 sister sweep 也是 advisory)
2. /idd-clarify 跟 /spectra-discuss 重疊:spectra-discuss 更廣(design space exploration),clarify 更窄(既有 issue body terminology / ambiguity / missing context)。Cross-link 互不重疊。
3. Terminology heuristic library 維護權:maintainer initial + 開放 PR contribute? Rule-of-three(同 misuse 出現 3 次升格進 canonical)?
4. idd-diagnose Step 0.5 gate 強度:hard refuse vs warn-continue?建議 hard refuse(類比 PR Gate Check),否則 surface 容易被 silent ignore。

---

Maintainer action(if accepting v3):

1. Open spectra change add-idd-clarify-skill-with-issue-step-48
2. SKILL.md for /idd-clarify(primitive,surfacing-only,annotation-only)
3. Patch idd-issue SKILL.md Step 4.8(auto-delegate to /idd-clarify)
4. Patch idd-diagnose SKILL.md Step 0.5(Clarity Surface gate)
5. references/terminology-canonical.md(seed with K-means / PCA / regression / Bayesian / classification 等,從 #804 incident captured patterns 起家)
6. Migrate this comment chain into change discussion.md(audit trail)

[kiki830621]

Diagnosis

Type

feature + meta(IDD plugin design gap — 新 skill /idd-clarify + 兩處 patch)

Root Cause / Analysis

IDD skill graph 缺第三 quality axis。三軸對應:

Axis	Existing safeguard	Skill
Confidence(客戶是否真的反映)	IC_R010 / Step 4.4	idd-issue Step 4.4 + idd-diagnose Step 3.4
Verbatim(原文是否被改寫)	IC_R007	source preservation in idd-issue Step 1
Terminology / Semantic accuracy(source 用詞是否正確;需求是否完整)	無	idd-clarify(新)

idd-diagnose 預設 issue 已 framed correctly。若 source 用錯誤 / 不精確 domain term(QEF #804「特徵值」→「分群變數」案例)或留隱含 missing-context(如 df_qef_customer_attributes 來源未指定),diagnose / plan / implement chain 繼承錯誤越走越歪。

Recursive evidence:本 session AI 在 design 階段連 3 輪過抽象(獨立 skill → diagnose sub-step → idd-issue inline step),user 連 3 輪 push back 切細(都不對 → composable primitive)。自證需要 third-party surfacing 機制。

Impact

• Affected files(預估 6 件 spectra change):

  • skills/idd-clarify/SKILL.md — new
  • skills/idd-issue/SKILL.md Step 4.8 — auto-delegate to /idd-clarify
  • skills/idd-diagnose/SKILL.md Step 0.5 — Clarity Surface gate(refuse if unresolved rows exist)
  • references/terminology-canonical.md — seed heuristic library(K-means / PCA / regression / Bayesian / classification 等)
  • openspec/changes/add-idd-clarify-skill/{proposal,design,tasks,specs}.md — spectra change artifacts
  • 既有 idd-issue / idd-diagnose Files Bound section + DOC_R009 三層同步

• User flows affected:

  • idd-issue 新建 issue:Step 4.8 auto-invoke /idd-clarify → annotation block append → 流程不變但 audit trail 多一層
  • idd-diagnose 跑既存 issue:Step 0.5 PR Gate 檢查 Clarity Surface unresolved → 有則 refuse,提示先 resolve
  • Retroactive audit:/idd-clarify #N standalone — 對既存 issue / cluster review 跑

• Downstream consumers:/loop / /idd-all 等 unattended caller 需確認 Clarity Surface annotation 不會 silent break(預期不會,因為 annotation 是 advisory + downstream gate-only refuse)

Strategy

Composable primitive pattern(per v3 design comment):

/idd-clarify <#N>                  ← standalone primitive
    ↑ delegated by
idd-issue (Step 4.8 auto-invoke)   ← orchestrator
    ↑ gated by
idd-diagnose (Step 0.5 PR Gate)    ← refuse on unresolved rows

Implementation tasks:

• T1. Write skills/idd-clarify/SKILL.md(surfacing-only contract,annotation-block output schema,status: surfaced/dismissed/resolved)
• T2. Patch skills/idd-issue/SKILL.md:加 Step 4.8 auto-delegate(Skill(skill="idd-clarify", args="#$NUMBER"))+ Step 0 Bootstrap TaskCreate entry
• T3. Patch skills/idd-diagnose/SKILL.md:加 Step 0.5 Clarity Surface gate(grep ### Clarity Surface + surfaced status → refuse with actionable message)
• T4. Write references/terminology-canonical.md:initial seed table(K-means 特徵值→分群變數 / PCA-K-means confusion / regression-ANOVA term mix / accuracy-RMSE / Bayesian-frequentist / unsupervised-supervised 等 6+ rows;rule-of-three for new entries)
• T5. Update Files Bound sections in idd-issue / idd-diagnose 各 SKILL.md
• T6. Migrate this issue's [META][idd-issue] terminology trust gap — source 用錯 domain term 時 AI 繼承錯誤 #135 + v2/v3 design comments into openspec/changes/add-idd-clarify-skill/discussion.md(audit trail per IDD MANIFESTO)
• T7. Bump plugin version in plugin.json(minor — new skill = backward compat additive)

Complexity

Spectra(SDD-warranted per Layer 2 + Layer 3)

• Layer 1 disqualifier:不命中(主要 deliverable 是 published skill + 修 published SKILL.md = 公共 API contract,不是 narrative / ad-hoc)
• Layer V (vagueness):V1≈2,V4≈2(已 iteration 三輪,user signal 清楚)— 未 trigger
• Layer 2(necessary):命中 — 新 skill 對 future callers 是 published API(SKILL.md = behavioral contract for downstream invocations)
• Layer 3(confirmation,需至少一個):
  • ✅ Modifying existing published spec normative behavior(idd-issue Step 4.8 + idd-diagnose Step 0.5 都改 MUST/SHALL clause)
  • ✅ 影響 2+ 既有 specs(idd-issue + idd-diagnose + 新 idd-clarify 三方一致性)
  • ✅ Architectural decision with long-term maintenance(三軸 model 是 future IDD skill design 的決策框架,不只是一次性 patch)

→ Verdict: Spectra

Risks

Risk	Severity	Mitigation
Self-reference recursion	LOW	/idd-all on #135 = AI 對 meta-design 自己 implement 自己。但 v3 已三輪 iterate,decision space 收斂。spectra-discuss 階段仍可挑戰
Backward compat break	MEDIUM	Step 4.8 + Step 0.5 都加新 step,不改既有 step。新 annotation block 對舊 issue 缺失 = ### Clarity Surface (not yet run) placeholder,downstream gate skip
Terminology heuristic over-trigger	MEDIUM	Surfacing-only(無 resolution force)+ user dismiss option per row + status 三態 + AskUserQuestion 不阻擋
Maintainer authority for terminology library	LOW	Rule-of-three(同 misuse 出現 3 次升格進 canonical)+ open PR contribution。初期 seed 6 rows 已足覆蓋常見統計 / ML 場景
/idd-all unattended mode 跟 Step 4.8 auto-invoke 衝突	LOW	Step 4.8 emit annotation block(non-blocking),不 fire AskUserQuestion;unattended 自然繼續

Residue

NSQL §4.6 — issue 意圖中無法 operationalize 的部分:

• Meta-rule about meta-design:本 session 「AI design 階段過抽象,需要 third-party surfacing」現象本身是否要 codify 成 plugin-level principle(類似 IDD MANIFESTO 加一條「skill 設計輪廓 audit」)。本 issue 不 operationalize 這個 — 它屬於 future iteration 議題。
• Terminology library governance:長期維護權、跨 plugin 共享(若 IDD 跟 spectra plugin 都要用)、versioning policy。初版 seed 6 rows 後的長期治理是 process governance,不是 single PR 能解決。
• Skill graph self-audit recursion:如果 /idd-clarify 自己 surface 自己 SKILL.md 的 terminology gap,應該怎麼處理?(recursive case;本 issue 接受 v3 design 已 stable 暫不處理)

---

Next steps:

依 Complexity = Spectra,本 issue 進 Step 4 routing(spectra-discuss / spectra-propose 選擇)。

Vagueness Pre-check

• V1: 2 — WHAT 清晰。Issue body + 2 個 design comments(v0/v3)三輪 iterate 後收斂到 explicit composable primitive 設計;Strategy section 列 6 件 Files Bound + 7 個 implementation tasks(T1-T7);Open questions 4 條都 bounded 未決而非全面模糊
• V4: 3 — ACCEPTANCE 中等清晰。Diagnosis Strategy T1-T7 checkboxes + v3 Maintainer action 5 deliverables 列出 concrete 產出,但無 explicit "PASS means X" / Definition of Done section;隱含 acceptance = 6 件 artifacts land + spectra change archive
• Triggered: no — both axes ≤ 3

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

Filed: #136 (idd-edit/idd-update primitive integration symmetry, enhancement P3), #137 (unattended Clarity Surface annotation contract gap, bug P2)

[kiki830621]

Implementation Complete

Posted by /idd-close gate handler — pre-implementation Strategy/Plan checkboxes superseded per v2.41.0+ rule (Implementation Complete > Checklist 全 [x] triggers supersession).

Checklist

• T1. Write plugins/issue-driven-dev/skills/idd-clarify/SKILL.md — completed in commit 812a0ba (395 lines, surfacing-only contract per design D2 + annotation-block schema status: surfaced/dismissed/resolved)
• T2. Patch plugins/issue-driven-dev/skills/idd-issue/SKILL.md — note: v3 design said Step 4.8 but scout caught collision with Split Umbrella SOP ([SOP] umbrella split flow should mandate commit log scan before filing sub-issues #11 v2.54+); landed as Step 4.6 per design D1 (between 4.5 Milestone + 4.7 Sister Sweep)
• T3. Patch plugins/issue-driven-dev/skills/idd-diagnose/SKILL.md — Step 0.5 Clarity Surface PR Gate added (hard refuse per design D2)
• T4. Write plugins/issue-driven-dev/references/terminology-canonical.md — 131 lines, 6 seed rows (特徵值/PCA-K-means/regression-ANOVA/accuracy-RMSE/Bayesian-frequentist/unsupervised-classification) + rule-of-three promotion threshold + open PR contribution + future plugin-level extension placeholder
• T5. Files Bound sections updated implicit via Step 4.6 + Step 0.5 SKILL.md patches; DOC_R009 三層同步 N/A(IDD plugin 無 Layer 1 .qmd / Layer 2 llm/*.yaml — single-layer SKILL.md authoritative)
• T6. Migrate [META][idd-issue] terminology trust gap — source 用錯 domain term 時 AI 繼承錯誤 #135 conversation chain into openspec/changes/add-idd-clarify-skill/discussion.md — completed, full v1→v2→v3→v4 design iteration + #804 triggering case + 4 Open Questions Resolution + recursive evidence captured
• T7. Bump plugin version: plugin.json 2.71.0 → 2.72.0(minor — new skill = backward compat additive)

Implementation Reference

• Commit: 812a0ba on PsychQuant/issue-driven-development:main (direct-commit mode per /idd-all Phase 0.6 graceful degrade — ralph-loop missing → direct-commit attended)
• Spectra change archived: openspec/changes/add-idd-clarify-skill/(proposal + design + 3 specs + tasks + discussion)
• Plugin version: 2.72.0
• Files changed: 9 (+1436 -2 lines)
• Sister concerns filed during diagnose + propose: [META][idd-edit / idd-update] should integrate /idd-clarify primitive for symmetric Terminology Surface (sister concern from #135) #136 (idd-edit/idd-update symmetry P3) / [META][unattended] Clarity Surface annotation interaction contract with /loop, /idd-all (sister concern from #135) #137 (unattended Clarity Surface contract P2) / [META] consider /goal substitution for some /ralph-loop refs in IDD plugin docs #138 (ralph-loop → /goal substitution P3)

Deferred (per spectra tasks.md [~] skip-with-reason)

• T9 / T10 / T11 self-tests — require plugin reload, post-merge smoke per spec scenarios in idd-clarify-skill / idd-issue-clarity-step / idd-diagnose-clarity-gate specs

Original Strategy task list in body and v3 design comment(2026-05-22)now superseded by this checklist per idd-close Step 0 v2.41.0+ supersession rule.

[kiki830621]

Closing Summary

Problem

IDD skill graph 只覆蓋兩個 issue-body 品質軸:

Axis	Existing safeguard	Skill / Step
Confidence(客戶是否真的反映)	IC_R010	idd-issue Step 4.4 + idd-diagnose Step 3.4
Verbatim(原文是否被改寫)	IC_R007	idd-issue Step 1 source preservation

第三軸 Terminology / Semantic accuracy(source 用詞是否正確;隱含 missing context)無對應 safeguard。idd-diagnose 預設 issue body 已 framed correctly,只做 routing + complexity;當 source 用了錯誤 / 不精確 domain term 或 隱含未說明的 data dependency,downstream chain(plan / implement / verify / close)繼承錯誤越走越歪。

Root Cause

Triggering incident:kiki830621/ai_martech_global_scripts#804(2026-05-21)— 客戶 docx 寫「特徵值」(eigenvalue) 實際意思是「分群變數 / distinguishing variable」(K-means 各群最具區辨力的變數)。AI 沿用 source verbatim 到 issue body + diagnosis comment;spec.md 階段意外修對是運氣不是 systematic safeguard。

Recursive evidence(本 session 4 instances of AI under-verification / over-abstraction):

1. D06 group registry collision(kiki830621/ai_martech_global_scripts#815)— AI 推薦 D06_01 derivation 沒 grep 既存 D06 owner(commit 9d49655 #313 product recommendation)
2. v3 design Step 4.8 collision(spectra-propose scout 抓到)— AI 推薦 Step 4.8 沒 grep 既存 SKILL.md(Split Umbrella SOP [SOP] umbrella split flow should mandate commit log scan before filing sub-issues #11 v2.54+ 佔用)
3. df_qef_customer_attributes 來源未指定 — spec / issue 都沒寫,AI 沿用「Expected schema upstream populated」假設(filed as follow-up kiki830621/ai_martech_global_scripts#817)
4. Design 三輪過抽象(v0 獨立 skill → v1 diagnose sub-step → v2 idd-issue inline → v3/v4 composable primitive 才對)— AI 在 design space 反覆 over-abstract,user 連 4 輪 push back 才落地

User explicit observation(2026-05-22):

• 「diagnose 是承認 issue 的情況下去做的事情」(直接定義 clarify vs diagnose boundary)
• 「失職 gatekeeper 問失職 gatekeeper」(否決 v0 AskUserQuestion 設計)
• 「連我自己這個 session 都是 case study」(recursive evidence acknowledged)

Solution

NEW /idd-clarify composable primitive + 既有 skills 兩處 patch + library seed + version bump:

/idd-clarify <#N>                  ← standalone primitive(retroactive audit)
    ↑ delegated by
idd-issue (Step 4.6 auto-invoke)   ← orchestrator(zero UX burden)
    ↑ gated by
idd-diagnose (Step 0.5 PR Gate)    ← hard refuse on unresolved rows

Key design decisions(per spectra change add-idd-clarify-skill):

• D1:Step 4.6(不 4.8)— scout 抓到 4.8 已被 Split Umbrella SOP 佔用;4.6 semantic order 在 sister sweep 4.7 之前
• D2:Hard refuse gate strength — 類比 PR Gate Check / idd-all-chain /idd-all-chain 設計缺陷: hard-coded cap=10 / 無 multi-root vs ripple-chain pre-flight / cap 超過時 silent truncate #119 fail-fast precedent;dismiss 1-step easy
• D3:Auto-trigger doc + pasted-text;--multi-finding SKIP(per-finding sub-invocation 成本太高)
• D4:Library maintainer seed 6 rows + rule-of-three promotion + open PR + future plugin-level extension
• D5:clarity = text-level audit;spectra-discuss = concept-level alignment;不互相 chain

Verification

• spectra validate add-idd-clarify-skill: ✓ valid
• Spectra analyze:0 Critical,27 Warning(cross-doc linkage non-blocking)
• Backward compat preserved:legacy issues without ### Clarity Surface block → idd-diagnose Step 0.5 backward-compat scenario silent proceed with log line
• User-explicit verify choice(direct-commit + attended mode)skipped 6-AI ensemble — 1436-line prose+SKILL.md diff,no runnable code;manual review reasonable
• T9 / T10 / T11 post-merge smoke deferred([~] skip-with-reason in tasks.md — plugin reload required for runtime tests;spec scenarios in idd-clarify-skill / idd-issue-clarity-step / idd-diagnose-clarity-gate 含完整 manual smoke plan)
• [META][idd-issue] terminology trust gap — source 用錯 domain term 時 AI 繼承錯誤 #135 self-validation:本 issue 自己經歷 idd-issue → diagnose → spectra-discuss → spectra-propose → spectra-apply → idd-close pipeline,實證 /idd-clarify v4 設計可 ship

Changes

• Commit ac401ae on PsychQuant/issue-driven-development:main (direct-commit mode per /idd-all Phase 0.6 graceful degrade — ralph-loop missing)
• Plugin version: 2.71.0 → 2.72.0(minor — new skill = backward compat additive)
• Files: 9 changed,+1436 -2 lines
  • New:plugins/issue-driven-dev/skills/idd-clarify/SKILL.md(395 lines primitive)
  • New:plugins/issue-driven-dev/references/terminology-canonical.md(131 lines library + governance)
  • Patched:plugins/issue-driven-dev/skills/idd-issue/SKILL.md(Step 4.6 + Bootstrap entry)
  • Patched:plugins/issue-driven-dev/skills/idd-diagnose/SKILL.md(Step 0.5 + Bootstrap entry)
  • Patched:plugins/issue-driven-dev/README.md(skill matrix + v2.72.0 changelog)
  • Patched:plugins/issue-driven-dev/MANIFESTO.md(三軸 framing section)
  • Patched:plugins/issue-driven-dev/.claude-plugin/plugin.json(version bump)
  • New:openspec/changes/add-idd-clarify-skill/(proposal + design + 3 specs + tasks + discussion)
• Sister concerns filed during diagnose + propose phases:
  • [META][idd-edit / idd-update] should integrate /idd-clarify primitive for symmetric Terminology Surface (sister concern from #135) #136 — idd-edit / idd-update primitive integration symmetry(P3)
  • [META][unattended] Clarity Surface annotation interaction contract with /loop, /idd-all (sister concern from #135) #137 — Clarity Surface annotation contract under unattended mode(P2)
  • [META] consider /goal substitution for some /ralph-loop refs in IDD plugin docs #138 — ralph-loop → /goal substitution scope question(orthogonal P3)
• Cross-repo follow-up:kiki830621/ai_martech_global_scripts#817 — QEF #804 customer_attributes source spec gap(unblocks QEF B.2 marketGrowthTrack / A.5 contracts / A.6 Wiki / close #804 once 老師 LINE 向創 答案)

Closes #135

Closing Follow-ups Filed (Step 3.5, IC_R011 #527)

• Filed: [META] terminology-canonical.md plugin-level extension architecture (closing follow-up from #135) #143 (terminology-canonical.md plugin-level extension architecture, P3 future)

Residue Acknowledgement (Step 3.6, IC_R011 #105)

Diagnosis residue 3 條全 filed as follow-up:

• Filed: [META] codify 'AI design 階段過抽象,需要 third-party surfacing' as plugin-level principle (residue from #135) #144 (codify 'AI design over-abstract' as plugin-level principle, P3 — wait rule-of-three)
• Filed: [META] terminology-canonical library long-term governance (residue from #135) #145 (terminology-canonical long-term governance, P3 — wait cross-plugin reuse)
• Filed: [META] /idd-clarify self-audit recursion edge case (residue from #135) #146 (/idd-clarify self-audit recursion edge case, P3 — wait actual case)

Distribution Sync (Step 6.5, v2.56.0+ #45)

• Detected: plugin (IDD repo is self-marketplace per .claude-plugin/marketplace.json — local ./plugins/issue-driven-dev path)
• Choice: chain executed inline (self-marketplace pattern — no separate cross-repo update needed)
• Outcome: marketplace.json issue-driven-dev.version bumped 2.71.0 → 2.72.0 (amended into commit ac401ae); next claude plugin update issue-driven-dev will pull v2.72.0 by users
• At: 2026-05-22