bug-prevention: #141 discussion-metadata helper must verify label existence + surface UI cache-sync hint

[kiki830621]

Problem

Follow-up to #141 (discussion-type issue metadata helper)。實作 #141 時，必須在 skill 內部加 label-existence verification step,否則會有兩類 silent bug:

Bug 1: gh label create succeeded 但 output 空白

$ gh label create discussion --repo X --description "..." --color 0E8A16
# (output 空白)

gh label create 成功時沒有任何 stdout output。Skill 跑完看不到「✓ created」signal，user 也不知道是否成功。如果用 gh label create ... 2>&1 | tail -2,只會看到 blank lines — 容易誤以為 silent fail。

實戰證據: 在 kiki830621/collaboration_liu-thesis-analysis discussion label setup 時:

$ gh label create discussion --repo ... --description "..." --color 0E8A16 2>&1 | tail -2
# (blank output — looked like fail, but actually succeeded)

User 後續看到 GitHub UI 的「Invalid value discussion for label」filter 提示時 first assumption 就是「label 沒建成功」。實際 label 是建成了,只是 GitHub UI autocomplete cache 沒同步。

Bug 2: GitHub UI autocomplete cache lag

剛建立的 label 在 GitHub web UI 的 issue filter dropdown 的 autocomplete 不會立刻 surface。User 在 issue list 用 label:discussion filter 時 GitHub UI 顯示:

"Filter contains 1 issue: Invalid value discussion for label"

這是矛盾的提示 — filter 找到 1 個 issue (真實結果),但 dropdown 同時提示 "Invalid value"。原因是 UI 的 label autocomplete 是 client-side cached,新建 label 要 hard refresh / 等 ~30 秒才會 sync 到 dropdown。

但是 Issue body 內的 label field、API、CLI 完全 work — 不是 server-side bug,只是 UI cache lag。

如果 #141 在 discussion-metadata helper 跑完後不提示 user「label 剛 created → GitHub UI 可能要 hard refresh」, user 第一個進去 issue list 看到「Invalid value」就會誤以為 skill 出 bug。

Type

bug (preventive — bake into #141 implementation)

Expected

#141 implementation 必須包含這 3 個 safeguards

Safeguard 1: Verify label exists post-create (not trust silent succeed)

# Step (b) Label suggestion 內,當 user 選 "Yes + auto-create if missing":

# 1. Try to create
gh label create "$LABEL_NAME" \
  --repo "$REPO" \
  --description "$LABEL_DESC" \
  --color "$LABEL_COLOR" 2>/dev/null

# 2. VERIFY by reading back (don't trust silent success)
if gh label list --repo "$REPO" --search "$LABEL_NAME" \
     --json name --jq '.[] | select(.name == "'$LABEL_NAME'") | .name' \
     | grep -q "^${LABEL_NAME}$"; then
  echo "✓ Label '$LABEL_NAME' verified in repo"
else
  echo "✗ ABORT: gh label create returned success but label not in list — investigate"
  echo "  Possible causes: API quota, permission, network. Re-run after diagnose."
  return 1
fi

為什麼必須 verify: gh label create 對於「已存在」case 會 silently noop (no error), 對於「成功 create」case 也是 silently succeed。無法從 exit code + stdout 區分這兩種 state。Verify-by-read 是唯一可靠 detection。

Safeguard 2: Verify label exists pre-add (for --add-label path)

# Step (b) 當 user 選 "Yes, add `discussion`" (不含 auto-create):

# Pre-flight check
if ! gh label list --repo "$REPO" --search "$LABEL_NAME" \
     --json name --jq '.[] | select(.name == "'$LABEL_NAME'") | .name' \
     | grep -q "^${LABEL_NAME}$"; then
  echo "⚠ Label '$LABEL_NAME' does not exist in $REPO"
  AskUserQuestion: "Auto-create now, or skip?" → option 1/2/3
fi

# Only if verified exist → proceed with --add-label
gh issue edit "$ISSUE_NUM" --repo "$REPO" --add-label "$LABEL_NAME"

為什麼: gh issue edit --add-label X 對於不存在的 label 行為 inconsistent (有時 error, 有時 server-side silently auto-create with default white color)。 Pre-flight verify 避開這個 edge case。

Safeguard 3: UI cache-sync hint post label creation

當 label 剛 created (新 created 不是既有的), 在 Step 5 report 階段加 hint message:

✓ Created label 'discussion' (#0E8A16 green) + assigned to issue #N

ℹ  GitHub Web UI 的 label autocomplete dropdown 可能要 hard refresh (Cmd+Shift+R)
   才能在 issue filter 看到此 label。
   如果 UI 顯示 "Invalid value discussion for label" — 不是 bug, 是 client-side cache lag.
   Filter 實際仍 work; gh CLI 仍可用 --label discussion。

為什麼: user 第一次看到 "Invalid value" 通常以為 skill 出 bug。 Preventive 提示節省 debugging trouble。

Implementation order

Safeguard 1 + 2 是 implementation 邏輯,寫在 Step 3.5 discussion-metadata helper 內。
Safeguard 3 是 user-facing prose hint,加在 Step 5 回報段落。

Actual

#141 spec 目前 (filed 1 hr ago) 沒有 verify-by-read pattern + 沒有 cache-sync hint。如果直接 implement,會碰到上述兩 bug:

• Silent label-create succeed → user 不知道有沒有成功 → debug 浪費 5-10 分鐘
• UI cache lag → user 第一次看到 "Invalid value" → 以為 skill bug → report false positive

Impact

Reviewer / collaborator UX

每次 IDD skill 跑 label setup 都會碰到一次「為什麼 UI 顯示 invalid value 但 CLI 說 OK」的 confusion。 第一次使用者特別 vulnerable — 沒有「這是 cache lag 不是 bug」的 mental model。

Developer UX

Skill maintainer (future-me / future-someone) 看到 #141 spec 沒 mention verification,implement 時直接 trust gh label create 的 silent succeed,99% case work fine、1% case silent fail without observable signal — 這 1% 都會變成 production bug report。

Audit trail

如果 label create silently fail 而 skill 沒 verify,後續 --add-label 會 fail (label 不存在), skill 整個 invocation 在 wrong state — 一般 error handling 也許 catch 到, 但 root cause (label 沒建成) 看不出來。 silent failure 是 IDD discipline 最痛的痛點 (#103 F4 vocabulary Layer M, "Misleading silent succeed")。

Open design questions

1. Verify-by-read 跑幾次: 一次 gh label list --search X 夠嗎? 還是要 retry with backoff if first read shows missing (in case server-side replication lag)?

   建議: first read 即可 ─ GitHub API 對 label 是 strongly consistent (label create 後立即 readable)。 Cache lag 只在 web UI autocomplete dropdown。

2. Safeguard 3 hint 是否每次都 print: 還是只在「剛 created (not 既有 reuse)」case print?

   建議: only on fresh create, 既有 label reuse 不 print (no cache-sync issue)。

3. discussion label color/description 的 sensible default: feat: discussion-type issue metadata helper — assignee / label / milestone / native relationships auto-surface #141 提了 #0E8A16 green + "Open question awaiting decision or input"。 是否 hard-code 或 config-overridable?

   建議: config-overridable via .claude/issue-driven-dev.local.json:

   {
     "discussion_label": {
       "name": "discussion",
       "color": "0E8A16",
       "description": "Open question awaiting decision or input"
     }
   }

4. Safeguard 2 (pre-flight verify) 跟 既有 --label $TYPE (在 Step 3 已用) 是否衝突: 既有 --label $TYPE (bug/feature/refactor/docs) 都是 default GitHub label (預設存在), pre-flight verify 預期 always pass — 只對 custom label 真的需要。

   建議: pre-flight verify 僅對非 default-set labels 跑 (discussion, epic, custom user labels) — bug/feature/refactor/docs 跳過 (GitHub repo 預設都有)。

Related

• #141 — discussion-metadata helper feature 本體 (本 issue 是 implementation 前的 bug-prevention spec)
• gh label create silent succeed pattern 在 IDD ecosystem 其他 skill 可能也有 (e.g. milestone create, attachments release create) — 這些都該套用同 verify-by-read pattern as systematic discipline
• IDD anti-pattern: "trust silent succeed without verify-by-read" — 應該寫進 references/skill-anti-patterns.md (如果已存在的話)

Notes

實戰觸發:Liu thesis discussion label setup 時 user 看到 GitHub UI「Invalid value discussion for label」filter 提示。 經 verify 證實是 client-side autocomplete cache lag, 不是 server-side bug。 但 user 第一個 assumption 是「skill 出 bug」 — preventive hint 可以節省這次 debugging。

如果 #141 不 bake 這些 safeguards into implementation,第一次跑 discussion-metadata helper 的 user 會碰到同樣 confusion,重複犯本次 session 已經發現的 bug。

---

cc maintainer: 把這個寫進 #141 design before implementation start。

---

Current Status

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

Key Decisions

• Complexity = Simple；與 feat: discussion-type issue metadata helper — assignee / label / milestone / native relationships auto-surface #141 同批實作（cluster-PR eligibility: same-file + same-root）
• Next: 隨 feat: discussion-type issue metadata helper — assignee / label / milestone / native relationships auto-surface #141 實作

[kiki830621]

Diagnosis

Type

bug-prevention（#141 helper 的 existence 驗證規格）

Root Cause / Analysis

兩類 silent bug 已由 issue 實證：gh label create 成功時零 stdout（誤讀為 fail）；label 已存在時 create 失敗但 UI cache 可能顯示不同步。規格化為 #141 實作的內建 step：create 前 gh label list --json name existence 檢查 → 存在 skip、不存在 create 後 re-query 驗證（不信 stdout）、輸出明確 ✓/✗ + UI cache-sync hint。

Impact

併入 #141 的 metadata helper 實作（同檔同 step）

Strategy

• existence-check → create → re-query verify 三段式（label 與 milestone 同 pattern）
• 輸出契約：每項 metadata 動作有顯式結果行
• 測試：existence/不存在/已存在三分支

Conflict Class

C_shared_module_coord — 與 #141 同檔同步（實質上是 #141 的驗收條款）。

Complexity

Simple（規格已由 issue 完整給定，實作依附 #141）

Risks

(併入 #141 風險面)

Residue

(none)

Vagueness Pre-check

• V1: 1、V4: 1 — 規格與實證俱全
• Triggered: no

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

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

(none)

---

Source: /idd-all batch drain (unattended), 2026-07-06

[kiki830621]

🔍 idd-verify → ✅ PASS（round-1 修復後）— 實作在 PR #248，完整 verify report：#248 (comment)

停在 verified，未 merge / 未 close（IDD 契約）。