feature: milestone-first SOP for cross-cluster tracking (replace Epic issue anti-pattern)

[kiki830621]

Problem

Original text (kiki830621 dogfood session, 2026-05-12, repo PsychQuantHsu/psychophysical_representations):

「Milestone-first 是這次最大的設計升級:用 GitHub native primitive(milestone)而非 Epic issue 來追蹤 cross-cluster,直接避開「Epic 跑 IDD lifecycle 不合適」的 mismatch。 user 一句『還是你可以創 milestone 來追蹤』就把這個 stuck pattern 切開了。」

— Source: academic repo dogfood session,/idd-list 顯示 Epic issue (#24) 為 (no phase) 製造噪音 → user 提議改用 milestone → 同 session 建 milestone + migrate 14 issues + close Epic

觀察到的 mismatch

/idd-list 把 issue 依 IDD lifecycle phase(created / diagnosed / implemented / verified / needs-fix / closed)分類。Phase 概念是針對 single-deliverable actionable issue 設計。

但 Epic issue(GitHub OSS 慣用的 cross-cluster tracking pattern)沒有 lifecycle phase 概念 — 它是 meta-tracking artifact,sub-issues 自己跑 IDD lifecycle,Epic 本身的 phase 永遠是 stuck (no phase) 或 manually tracking。

→ 結果:/idd-list 把 Epic issue 顯示為 (no phase) + 建議「/idd-update #N 先同步狀態」,但 Epic 本來就不該進 lifecycle,user 收到的是 false signal。

比 Epic 更好的 native primitive:GitHub Milestone

維度	Epic issue	GitHub Milestone
進度視覺化	手動勾 task list checkbox	自動 progress bar(closed/total ratio)
Sub-issue 加入	body 列 - [ ] #N(手動 sync)	first-class attach(gh issue edit --milestone)
Filter	references: #N search	--milestone "..." flag
Close 同步	手動 update Epic body	自動 state update on sub-close
IDD lifecycle phase 適用	❌(製造 (no phase) 噪音)	✅(milestone 不進 lifecycle 是 GH-native 設計)

Type

feature / docs

Expected

把 「cross-cluster tracking 用 milestone 而非 Epic issue」 升格為 IDD plugin 的 正式約定,涵蓋:

A. Documentation update

• plugins/issue-driven-dev/CLAUDE.md(plugin-level conventions)— 加 section「Cross-cluster tracking conventions」:

  • 規則:cross-cluster work 一律用 GitHub milestone,不開 Epic issue
  • 範例:gh api repos/.../milestones -f title="..." + gh issue edit --milestone "..."
  • 例外:若 cross-cluster work 本身有 actionable deliverable(rare,如「cluster retrospective writeup」),仍可開 issue + assign milestone

• plugins/issue-driven-dev/skills/idd-issue/SKILL.md(filing rule)— 加 anti-pattern entry:

  • 「想開 [Epic] xxx 標題的 tracking issue」→ refuse + 引導用 gh api .../milestones 建 milestone

• plugins/issue-driven-dev/skills/idd-diagnose/SKILL.md(diagnose rule)— 加 Layer 1 disqualifier:

  • 「meta-tracking issue(無 single deliverable)」→ refuse to diagnose + 引導 close + migrate to milestone

B. /idd-list heuristic upgrade

• 偵測 issue 是 Epic-style(title 開頭 [Epic] / Epic: / body 含 task list of #N only,無 actionable deliverable)
• 顯示 [(epic, no phase)] 而非 [(no phase)] + suggest「gh api .../milestones migrate + close Epic」
• 不再 surface 為 /idd-update 建議

C. (Optional, follow-up) /idd-milestone skill

若 milestone 操作頻率高(create / attach issues batch / close),可考慮抽 atomic skill:

• /idd-milestone create "<title>" --attach #X,#Y,#Z
• /idd-milestone list — show all milestones + progress
• /idd-milestone close N — close milestone(若所有 sub-issue 已 close)

本 issue 不直接動 milestone CLI scope;只先 SOP化 + heuristic。/idd-milestone 留 follow-up issue。

Actual

當前(v2.59.0)IDD plugin 沒提及 milestone。/idd-issue、/idd-diagnose、/idd-list、/idd-close 全部 default 把 cross-cluster tracking 引導到 Epic issue 模式。Dogfood case(academic repo #24)真實踩到 mismatch:

1. yfhsu 5/11 email → IDD 流程引導開 [Bundle test] Step 2: add API #24 [Epic] yfhsu 2026-05/06–/11 feedback cycle
2. Cluster work 跑了 1 週,[Bundle test] Step 2: add API #24 從沒進入 IDD lifecycle phase(始終 (no phase))
3. /idd-list 把 [Bundle test] Step 2: add API #24 一直顯示為 noise → user 提議用 milestone → migrate + close [Bundle test] Step 2: add API #24

→ 這次是 user 自己發現 mismatch。Plugin 不該依賴 user spot 這個 anti-pattern,該主動引導正確 primitive。

Impact

Affected files:

• plugins/issue-driven-dev/CLAUDE.md(add cross-cluster conventions section)
• plugins/issue-driven-dev/skills/idd-issue/SKILL.md(add Epic anti-pattern)
• plugins/issue-driven-dev/skills/idd-diagnose/SKILL.md(add Layer 1 disqualifier)
• plugins/issue-driven-dev/skills/idd-list/SKILL.md(add Epic detection heuristic + new suggestion)
• plugins/issue-driven-dev/README.md(documentation table)

Downstream:

• Dogfood repos already running IDD(academic + plugin marketplace 自己)立即受惠
• Existing Epic issues(若有)需 manual migration — 提供 migration cookbook

Acceptance criteria

• CLAUDE.md 含「Cross-cluster tracking conventions」section(milestone-first rule + 例外條件 + cookbook)
• idd-issue SKILL.md 含 Epic anti-pattern entry(refuse + 引導 gh api .../milestones)
• idd-diagnose SKILL.md Layer 1 disqualifier 含「meta-tracking issue」
• idd-list SKILL.md 含 Epic detection heuristic
• idd-list implementation(SKILL.md Step 3.x)偵測 Epic title pattern + body 結構,suggested next 改顯示 migration guidance
• CHANGELOG entry + version bump
• Cookbook(在 CLAUDE.md 或新 doc):「如何把既有 Epic issue migrate 到 milestone」step-by-step
• (Optional) Follow-up issue: /idd-milestone skill design

Related

• Dogfood source: PsychQuantHsu/psychophysical_representations milestone #1 (yfhsu 2026-05/06-11 feedback cycle — successful migration case)
• Sister(同 Insight 第 2 點): /idd-list blocked-state output mode(separate issue 即將 file)

---

Source: surfaced during /idd-list dogfood in academic repo session 2026-05-12 (PsychQuantHsu/psychophysical_representations)