IDD comment 過多觸發 GitHub notification fatigue — human-only vs AI-only 分流?

[kiki830621]

Problem

Original text (User report):
「有人反映說會有大量的通知很annoying」

Follow-up design idea:
「我在想每一個issue都要分成human, ai 看的，只有human看的要發通知？這可以做到嗎」
— Source: /idd-issue clarifying dialog, 2026-05-20

IDD workflow 在單一 issue 上會 post 大量 comment(diagnose / verify / update / sister sweep / linked-context / close summary…),每個 comment 都會觸發 GitHub notification(issue 訂閱者、被 @mention 的人、assignee)。實際使用者反映這個量級到「annoying」的程度 — 訂閱者收到一堆「AI 跟 AI 之間互看」的 comment,human 沒有 actionable 意圖。

使用者提出的 design proposal:

• 把 issue 上的 comment 分流成「給 human 看的」vs「給 AI 看的」
• 只有給 human 看的才觸發 GitHub notification
• 給 AI 看的 (process / audit trail) 留在 issue 但 mute

Type

feature(含 open design question:技術上能否做到 selective notification)

Expected

• 使用者訂閱 issue 後,只收到對 human 有 decision value 的 notification(例:idd-diagnose 完成等待 review、idd-verify 發現 blocker、closing summary)
• AI 之間的 process comment(每個 verify agent 的 raw output、idempotency check 紀錄、sister sweep 報告)仍寫進 issue 做 audit trail,但不觸發 notification

Actual

目前每個 IDD skill post 的 comment 都會走 GitHub 預設 notification 機制 — 所有 issue 訂閱者、被 ref 的 user、assignee 都會被 ping,無差別。一個 issue 跑完 /idd-all 可能產生 5-15 個 comment,全部都會推給 human。

Open question(待 diagnose 階段釐清)

1. GitHub 端是否支援 selective mute?可能方案:
   • 用 hidden HTML comment 或特殊 marker → user 自己設 notification filter
   • 改用 gh api 直接 PATCH issue body 取代 gh issue comment(edit 不發 notification,但失去時間軸)
   • AI process log 改寫到 separate place(.claude/.idd/issue-runs/*.jsonl 已有 audit trail,issue 上只留 human-facing summary)
   • GitHub native: subscription type / mention pattern 控制
2. 哪些 comment 該分成「AI-only」?需要 inventory 各個 idd-* skill 的 comment pattern

Impact

• Adoption blocker:notification fatigue 會讓使用者直接 unsubscribe issue 或關掉 IDD,等於放棄 audit trail
• Collaboration cost:被 @mention 拉進 issue 的 collaborator 體驗更差(他們對 AI 流程沒有 context)

Priority

P1 — 本週

Vagueness assessment

• V1 (vague WHAT) = 3 — 改善方向清楚(減少非必要通知),但具體拆分標準未定
• V4 (vague ACCEPTANCE) = 4 — done criteria 還沒明確;需要 diagnose 階段先回答 open question 1 才能寫出 testable acceptance

Linked-Context Siblings Filed (v2.48.0+ #529)

(none — no orphan sibling mentions in linked context)

---

Current Status

Phase: diagnosed
Last updated: 2026-05-21 by idd-diagnose

Key Decisions

• 開放問題 1 已解答:GitHub 不支援 author-side selective mute,但 author-side reduce 完全可行(gh issue edit --body PATCH 不觸發 notification、gh api PATCH /issues/comments/:id 不觸發 notification、jsonl 落地完全離 issue)
• Receiver 分類標準已定:human-facing = Diagnosis Report 完成 / final verify verdict / closing summary / user-initiated comment;AI-only = idd-verify raw agent output / audit trail PATCH / sister concern surfacing 記錄
• Strategy 採 3-phase rollout: Phase 1 idd-verify consolidation(highest leverage,獨立可上)→ Phase 2 全 skill comment-vs-body PATCH 紀律 audit + notification-discipline.md rule → Phase 3 measurement + opt-out env var
• Complexity verdict = Spectra(Layer 2 published skill API + Layer 3 cross-spec impact + architectural decision 同時命中)
• Routing 決定: 走 spectra-discuss(default)先對齊 acceptance metric / jsonl schema / rollout 順序

Scope Changes

• Sister concerns filed [bug] AI-generated comment 中的 @mention 可能繞過 tagging-collaborators 5-step protocol (sister concern from #116) #117(@mention audit gap in AI-generated comments,latent bug)+ [refactor] Issue body archival 策略 — 防止 audit section 長期堆積導致可讀性下降 (sister concern from #116) #118(issue body archival 策略,QoL refactor)— 不納入 IDD comment 過多觸發 GitHub notification fatigue — human-only vs AI-only 分流? #116 scope

Blocking

• 等 /spectra-discuss 對齊以下 open questions: acceptance metric proxy 怎麼定?jsonl schema(verify-runs/<run_id>.jsonl)欄位?phase 1/2/3 是否一次走完還是逐 phase ship?

Commits

• (none)

[kiki830621]

Diagnosis

Type

feature(含 design exploration)

Analysis — 需求拆解

1. 痛點量化(per /idd-all issue lifecycle)

各 skill 的 gh issue comment 計數(grep skill source):

Skill	Comments posted	Body edits	受眾分類
idd-issue	2	9	human
idd-diagnose	2	2	human(Diagnosis Report 是給 human 看的)
idd-plan	1	1	human
idd-implement	2	0	mixed(commit refs)
idd-verify	7	1	AI-heavy(6 agent reports + 1 summary)
idd-close	4	6	human
idd-update	0	2	human-relevant(body sync)
Total	~18 / issue	~21	—

→ idd-verify 占約 40% notification volume,且 6 個 raw agent report 是「AI 寫給 AI 看的 audit trail」,human 只需 final consolidated verdict。這是 highest-leverage 攻擊點。

2. GitHub notification 機制(open question 1 的答案)

GitHub 不提供 author-controlled selective mute。每個 gh issue comment 都會觸發訂閱者 notification — 沒有 "silent comment" API、沒有 hidden marker filter、HTML comment 不會 suppress notification。

但有幾條繞道:

機制	是否 fire notification	適用場景
gh issue comment	✓ fire	human-facing summary
gh issue edit --body(PATCH body)	✗ no fire	累積 audit trail 到 body section
gh api PATCH /issues/comments/:id(edit existing comment)	✗ no fire	修補既有 comment(idd-diagnose Step 3.4 已用此 pattern)
Local file(jsonl / md)	✗ no fire	AI process log,user 看 repo 不看 issue
Bot account 分離 + per-user filter	fire 但 user 可 mute by sender	heavyweight,需 separate PAT

→ 結論:author-side mute 不可能,但 author-side reduce 完全可行。把 AI-only content 從 comment 改 routing 到 body PATCH / local jsonl,notification volume 可降 60-80%。

3. 受眾分類標準(open question 2 的答案)

Human-facing(必須 fire notification):

• Diagnosis Report 完成(等 human review routing 決定)
• idd-verify final consolidated verdict(pass/fail + blocker count)
• idd-close closing summary(work shipped 的紀錄)
• User-initiated idd-comment(decision / question / errata)
• Blocker / failure 需要 human intervention

AI-only(改 routing,不該 fire notification):

• idd-verify 6 個 raw agent output(現在各自一個 comment,應該合併或寫 jsonl)
• Step 3.4 / Step 3.6 / Step 4.7 audit trail 補完(已是 gh api PATCH 不 fire,維持)
• Sister concern surfacing 的 ### Sister Concerns Filed audit 區塊(同上)
• Idempotency check 紀錄
• Linked-context sweep 報告

Impact

• 影響的 skill:idd-verify(主要)、idd-close、idd-diagnose(次要)
• 影響的使用者流程:/idd-all lifecycle 收到的 notification 量
• 不影響:audit trail 完整性(content 仍在 issue / jsonl,只是 channel 改變)、commit/PR-ref notification(GitHub 機制)

Strategy

Phase 1 — idd-verify consolidation(highest leverage,獨立可上):

• 6 個 agent raw output 合併成 1 個 consolidated comment(已有 summary,需把 raw 改 collapsible <details> 區塊或寫 jsonl)
• 引入 .claude/.idd/verify-runs/<run_id>.jsonl 存 raw agent output(mirror multi-finding mode 的 jsonl pattern)
• Final comment 只含 verdict + blocker list + jsonl pointer footer

Phase 2 — comment vs body PATCH 紀律 audit:

• Inventory 每個 skill 目前 gh issue comment 呼叫,標 human / AI 受眾
• AI-only 的改 gh issue edit --body append section 或 gh api PATCH edit existing comment
• 寫 rules/notification-discipline.md rule 給後續 skill 開發遵循

Phase 3 — measurement + opt-out:

• 加環境變數 IDD_VERBOSE_COMMENTS=true 讓使用者可以暫時開全部 comment(debug 用)
• 在 dispatch summary 顯示「this run posted N comments(target ≤ 5)」讓 maintainer 觀測 regression

Complexity

Spectra

觸發層:

• Layer 1 disqualifier:不命中(不是 narrative / ad-hoc / typo)
• Layer V:V1=3 V4=4 → V4 trigger(see Step 3.4 below)
• Layer 2(necessary):命中 — 改的是 IDD plugin skills 的 published behavior contract;skill 的 comment 政策是 future maintainer 寫新 skill 時要遵循的 spec
• Layer 3(confirmation):命中
  • 影響 2+ 既有 specs:idd-verify / idd-close / idd-diagnose / 後續 skill 的 comment 規範
  • Architectural decision with long-term maintenance implications:確立「AI-only output 走 jsonl 而非 comment」是 cross-skill 紀律
  • 需要新增 rule file(notification-discipline.md)為後續 IDD skill 設規範

Layer 2 + Layer 3 同時命中 → Spectra。建議先 /spectra-discuss 對齊「receiver classification 標準」「jsonl schema」「rollout 順序(全部一次改 vs phase 1 先上)」這些 open questions 再寫 proposal。

Risks

• Audit trail completeness:把 AI raw output 從 comment 移到 jsonl,使用者要回頭 audit 時需要新工具或 explicit pointer。如果只移除沒留 link,等於丟失 audit。
• Phase 1 ship 即可體感改善 vs 完整 phase 3 才見效:phase 1 (idd-verify 合併) 立即砍掉 40% volume,應該獨立 ship 不等 phase 2/3
• GitHub native mention 仍會 fire:如果 AI-only comment 內含 @user,即使 body PATCH 也會 trigger mention notification。需 audit @mention 規則(目前 tagging-collaborators 5-step 已有約束,但 AI 內部互引可能漏掉)
• idd-update body PATCH 已是 silent 但 issue body 變很長:長期累積會讓 issue body 難讀,需 archival 策略(例如超過 N section 移到 .claude/.idd/issue-history/)

Residue

NSQL §4.6 殘留 — 無法 operationalize 的部分:

• 「annoying 到什麼程度算 done」是主觀體感,沒有可量化 acceptance(看是 issue lifecycle 平均 < 3 個 notification 算成功嗎?還是 user 反饋不再抱怨?)。建議在 spectra-discuss 階段定義一個 proxy metric(例:idd-verify 從 7 comment → 1 comment,可作為 phase 1 acceptance)。
• 第三方 IDD 使用者(plugin 安裝者非開發者)對「哪些 comment 該 silence」的偏好,本 issue 沒涵蓋。預期他們的 default 跟 maintainer 一致,但若有反饋差異需要再開 sibling issue。

Vagueness Pre-check

• V1: 3 — direction 清楚 (減少非必要 notification);分類標準在 Strategy phase 2 列為 explicit step
• V4: 4 — done criteria 未明確;phase 1 ('idd-verify' 6→1 comment) 可作為 proxy metric 但整體 acceptance 仍 vague(see Residue)
• Triggered: yes (max=4)
• User choice: proceed anyway
• Effect: routing 進 Step 3.5,acceptance metric 留待 spectra-discuss 階段對齊

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

Filed: #117, #118

• [bug] AI-generated comment 中的 @mention 可能繞過 tagging-collaborators 5-step protocol (sister concern from #116) #117 — @mention audit gap in AI-generated comments(latent bug)
• [refactor] Issue body archival 策略 — 防止 audit section 長期堆積導致可讀性下降 (sister concern from #116) #118 — Issue body archival 策略(quality-of-life refactor)