feat: discussion-type issue metadata helper — assignee / label / milestone / native relationships auto-surface

[kiki830621]

Problem

當 /idd-issue 建立一個 討論型 issue（type=docs / 純 plain-language summary / 等決定 / 等 collaborator 提供資訊 / advisor meeting briefing 等）時，現行 skill 不會 surface 應該設的 GitHub metadata：

• Assignees（誰是 next-action 行動方）
• 適當 label（discussion 區分於 implementation issue）
• Milestone（若是時間綁定 deliverable 例如「next advisor meeting」）
• Native relationships（GitHub 2024+ addBlockedByDependency 等 GraphQL mutation，比 body 內 #N text reference 更結構化）

實戰案例（kiki830621/collaboration_liu-thesis-analysis）：

Issue #36 / #37 / #38 都是「給人讀的 discussion 型 issue」(thesis advisor meeting prep)，body 內 cc @HsuanYuLiuuu 等她回應。建立後 user 才意識到應該設 GitHub right-sidebar metadata — assignee=HsuanYuLiuuu、discussion label、milestone="Advisor Meeting 2026-05-28" 把 3 個 issue 都掛上去。這些 metadata 是事後手動補的，理想上 /idd-issue 在 discussion-type 偵測時應該自動 surface。

Type

feature

Expected

Detection: 觸發 discussion-type metadata helper 的條件

任一命中 → 啟動本 helper:

1. Explicit flag: --type discussion 或 --discussion
2. Body content heuristic:
   • Title / body 含「給人讀」「review feedback」「summary」「briefing」「整理」等 plain-language signal
   • Body 含 cc @<login> mention pattern 但本身是 plain-language doc 而非 bug / feature 描述
   • Type=docs AND body 含 question marks / open decisions
3. Cross-reference density: body 含 ≥3 個 #N references 但本身不要求 implementation

Helper behavior (Step 3.5 between issue creation + Step 4 attachment)

當 detection 命中 → 跑以下 sub-steps（all advisory, AskUserQuestion based）:

(a) Assignee suggestion

從 body 內已通過 tagging-collaborators 5-step protocol 的 @login mentions 抽出來，建議 assign 給他們：

AskUserQuestion:
  "Detected discussion-type issue with @HsuanYuLiuuu in body.
   Assign as primary recipient? (她是 ball-in-her-court 行動方)"
  options:
    - "Yes, assign @HsuanYuLiuuu"
    - "Pick different assignee" → second-level: list collaborators
    - "Skip — no assignee"

(b) Label suggestion

AskUserQuestion:
  "Add `discussion` label? (區分於 implementation issue)"
  options:
    - "Yes, add `discussion`"
    - "Yes + auto-create if missing in repo"   ← create label with default color + description
    - "Skip — use only explicit type label"

Auto-create fallback: 若 user 選「Yes + auto-create」但 repo 沒這個 label，自動建：

gh label create discussion \
  --repo $REPO \
  --description "Open question awaiting decision or input" \
  --color 0E8A16

(c) Milestone suggestion (only if time-bound signal detected)

Heuristic for time-bound:

• Body 含「next meeting」「next sprint」「下次 meeting」「下週」「month-end」等 deadline reference
• 或 cross-reference 到既有 milestone 內 issue

AskUserQuestion:
  "Detected time-bound discussion (mentions 'next advisor meeting').
   Assign to milestone?"
  options:
    - "Pick existing milestone" → list open milestones
    - "Create new milestone" → AskUserQuestion(title, date)
    - "Skip — no milestone"

(d) Native relationships (GitHub 2024+ GraphQL)

從 body 內 #N references 抽出，suggest 用 GitHub native "Relates to" / "Parent of" / "Blocked by" 而非純 text reference:

AskUserQuestion (per #N reference):
  "Body references #24. Set native relationship?"
  options:
    - "Related to #24"           (default)
    - "Parent of #24"            (this issue is the parent)
    - "Child of #24"             (this issue is the child)
    - "Blocks #24"
    - "Blocked by #24"
    - "Text reference only"      (skip native, leave as body text)

技術實作: gh api graphql -f query='mutation addBlockedByDependency...' (already used in v2.52.0+ --blocked-by flag for bundle mode — reuse code path)

Implementation: where to add

最自然的 insertion point: 新增 Step 3.5: Discussion Metadata Helper, 在 Step 3 (issue creation) 之後 Step 4 (attachment upload) 之前。

理由:

• 必須在 issue 已 create 之後 (才有 issue_number 可以 edit metadata)
• 必須在 attachment upload 之前 (這樣同一個 metadata-setup ceremony 統一在一個位置)
• 跟既有 Step 4.7 (Sister Sweep) Step 4.8 (Split Umbrella SOP) 同 advisory 性質

Bootstrap task list 新 stage task

TaskCreate(name="discussion_metadata_helper",
           description="Step 3.5 (v2.71.0+, #XXX): if detection hits, AskUserQuestion 4-pass (assignee / label / milestone / native relationships). Advisory, non-blocking. Skip if no signal.")

只在 detection 命中時 create 這 task；single-issue + bug 等 standard case 不 create.

Actual

現行 /idd-issue 對 discussion-type issue 完全不 surface metadata:

1. 沒 assignee suggestion → user 手動 gh issue edit --add-assignee X
2. 沒 label suggestion (除非 user explicit --label flag) → 純 --label $TYPE (bug/feature/refactor/docs) 不夠精細
3. 沒 milestone integration (除非 source 是 docx 觸發 Step 4.5 auto-milestone)
4. 沒 native relationship suggestion → body 內 #N references 全部停留在 markdown text (GitHub sidebar 不會 reverse-render backlinks)

Impact

Reviewer / collaborator UX

• 進 repo 看 issue list → 沒 discussion label, 不知道哪個是「正在等決定」vs「正在 implement」
• 看單一 issue → 沒 assignee, 不知道 ball-in-whose-court
• 沒 milestone grouping → advisor meeting 前要手動掃 list 抓 "要帶討論的 issue"

Author UX

每次建 discussion issue 後手動 gh issue edit --add-assignee X --add-label discussion --milestone "..." × N issue → tedious + 容易漏

Audit trail

Body 內 #N markdown reference 在 GitHub sidebar 不 reverse-render — 從 #24 sidebar 看不到「#38 references this issue」。Native relationship 才有 backlink。對長期 issue tree 追溯影響大。

Open design questions

1. Detection heuristic 精確度: 哪些 signal 應該 trigger helper? 過度敏感會 friction（每個 docs issue 都問四遍），不敏感會錯過真正討論型 issue。建議: opt-in --discussion flag 為 primary trigger, body heuristic 為 fallback (預設 off, 透過 config discussion_metadata_heuristic: true opt-in)

2. Label naming convention: discussion 是最 generic 的命名，但 ecosystem 內可能已 reserve 給其他用途 (GitHub Discussions 是另一個 feature)。Alternative naming:

   • awaiting-decision
   • needs-input
   • for-review (跟 PR review label 衝突)
   • topic:discussion

   建議: 用 user 偏好的 (可在 config 中 discussion_label: "discussion" 配置)，default discussion

3. Milestone auto-create timing: 若 user 選 "Create new milestone" 但 due_date 未設,要不要 push to set due_date? Hard requirement 會 friction。建議: optional due_date,空 = open-ended (適合 "Backlog" type milestone)

4. Native relationship 跟 body text reference 重複: 設了 native "Related to [Bundle test] Step 2: add API #24" 後, body 內仍有 #24 markdown text。Github render 兩個都顯示。要不要建議 user 移除 body text reference 避免 redundancy? 建議: 保留 body text reference — markdown reference 在 issue body 內保留 inline context (e.g. "see [Bundle test] Step 2: add API #24's verify report"), 跟 native "Related to" backlink (sidebar) 是互補不重複

5. Pre-existing label not configured: 若 repo 沒 discussion label, auto-create 的 default color (0E8A16 green) 跟 user 既有 label color scheme 可能衝突。建議: auto-create 時用 GitHub default green; user 不滿意可手動改 label color

Related

• --mention flag (v2.32.0+) — tagging-collaborators 5-step protocol 已 verify @login，本 feature 可 reuse 該 verified list 作為 assignee candidates
• Step 4.7 Sister Sweep — 同 advisory 風格,non-blocking AskUserQuestion 3-option pattern
• v2.52.0+ --bundle-mode GraphQL addBlockedByDependency mutation — 同 code path 可重用於 native relationship suggestion
• v2.55.0+ Multi-finding mode — relationship suggestion 在 multi-finding routing 中尤其重要 (dispatch 到既存 issue 時 default "Comments to" 但可能 user 想要 "Edits + Related to")

Implementation effort estimate

Component	Effort	Risk
Detection heuristic (regex on body + flag parsing)	S (1h)	Low
Assignee AskUserQuestion + gh issue edit --add-assignee	S (30 min)	Low — reuses existing --mention collaborator list
Label auto-create + --add-label	S (30 min)	Low
Milestone create / pick (gh api milestones)	M (1-2h)	Medium — milestone API surface比 issue API 複雜
Native relationship GraphQL mutation	M (1-2h)	Medium — already exists for --blocked-by, but needs UI for relationship type picker
Step 3.5 SOP doc + AskUserQuestion prose	M (1h)	Low
Test fixtures + dogfood iteration	M (2h)	Medium

Total estimate: ~6-8 hours for v1 implementation.

Notes

實戰觸發案例：Liu thesis #36 (Age multiverse) / #37 (sister fix narrative summary) / #38 (HsuanYuLiuuu review feedback) 都是 discussion-type issue. 3 個 metadata 都是事後手動 setup（建 discussion label + assign HsuanYuLiuuu + 建 "Advisor Meeting 2026-05-28" milestone）。若 /idd-issue 在建 #36 時就 surface 這些 prompt, 後續 #37 #38 配套 setup 自動沿用，省掉 ~5 分鐘手動操作 per discussion issue.

---

Current Status

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

Key Decisions

• Complexity = Plan、C_shared（idd-issue/SKILL.md）
• unattended = surface-only；outward-facing metadata 絕不 auto-set
• Next: cluster merge 後與 bug-prevention: #141 discussion-metadata helper must verify label existence + surface UI cache-sync hint #142 相鄰實作

[kiki830621]

Diagnosis

Type

feature（idd-issue discussion-type metadata surfacing）

Root Cause / Analysis

discussion-type issue 的 metadata（assignee/label/milestone/native relationships）在建案時不被 surface，事後人工補 — collaboration_liu 案例的四項全中。偵測信號：type=docs / body 含「等 X 回覆/確認」/ meeting briefing pattern。GraphQL native relationships（addBlockedByDependency）比 body text ref 結構化。

處置形狀：偵測到 discussion-type → surface 建議 metadata 清單（attended：AskUserQuestion 確認；unattended：只 surface 到 output 不 auto-set — assignee/milestone 是 outward-facing 動作）。與 #128 auto-mention 分工：本案管 sidebar metadata，#128 管 body @mention。

Impact

• skills/idd-issue/SKILL.md（discussion-type 偵測 + metadata surface step）；bug-prevention: #141 discussion-metadata helper must verify label existence + surface UI cache-sync hint #142 的 label-existence 驗證為其內建前置

Strategy

• discussion-type 偵測 heuristic（type/body pattern）
• metadata surface：assignee 候選（從 body 被點名者，走 feat: collaborator config in idd-config — record GitHub login, email, name, aliases for tagging accuracy #86 表 + 5-step）、label discussion（經 bug-prevention: #141 discussion-metadata helper must verify label existence + surface UI cache-sync hint #142 existence 驗證）、milestone（時間綁定偵測）、blocked-by GraphQL
• attended 確認 / unattended surface-only 分流
• 測試 fixtures

Conflict Class

C_shared_module_coord — skills/idd-issue/SKILL.md（cluster branch 已動；#221 也動）；排 cluster merge 後與 #221/#142 相鄰。

Complexity

Plan（Layer P：多 metadata 面 + outward-facing 邊界）
[Plan tier deliberation skipped under unattended mode]

Risks

• Assignee 誤設通知不可逆 → 一律走 5-step + confirmation；unattended 絕不 auto-set

Residue

milestone 自動建立（不存在時）屬 #142 同類 existence 家族，併入實作。

Vagueness Pre-check

• V1: 2 — 四項 metadata 明確；偵測 heuristic 由 diagnosis 定案
• V4: 2
• Triggered: no

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

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

(none — #142 既存為其 bug-prevention 對)

---

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 契約）。