[SOP] umbrella split flow should mandate commit log scan before filing sub-issues

[kiki830621]

Problem

Encountered 2026-05-04 in ai_martech_global_scripts session:

When splitting an umbrella issue into N sub-issues (the established pattern that #502 → 6 sub-issues + #462 → 2 sub-issues etc), it's possible to file sub-issues for work that has already shipped in commits made before the umbrella was split.

Concrete recurrence

• ai_martech_global_scripts #502 umbrella created 2026-04-29 01:42 UTC
• Spectra change qef-attribute-bridge-types-and-na-handling shipped via commit 7292219 at 2026-04-29 09:10 UTC — addressed scope 1 + scope 2 of #502
• Session @ 2026-05-04 split #502 into 6 sub-issues (#536-#541), including:
  • #536 = scope 1 (Layer 1 type-mismatch)
  • #537 = scope 2 (Layer 0 generator NA-scanning)
• Both were already done but filed anyway (4-day-old commit existed).
• Required retroactive close with closing summaries pointing at 7292219.

Wasted ~10 min audit + creates noise in Open issue list during split-to-retro-close window.

Proposed Process Fix

When the user invokes a split-umbrella workflow, the operating skill / agent should:

1. Before filing each sub-issue, search commit log for keywords from the umbrella body:

   git log --oneline --grep "#<UMBRELLA>" --since="<umbrella creation date>"
   git log --oneline --grep "<spectra change name if mentioned in body>"

2. Read commit messages for trailers like (#<umbrella> scope <N>) indicating which scopes have already shipped
3. Surface to user before filing: "sub-issue #N candidate maps to commit XXX from ; already shipped — file as retroactive tracker, or skip?"
4. Optionally check openspec/changes/archive/ for matching spectra change names

Suggested scope

Either:

• (a) New skill: /idd-split-umbrella <issue#> that does pre-flight check
• (b) Enhancement to existing skill: /idd-issue with --split-from <#> flag
• (c) Documentation only: add SOP reminder

Type

enhancement (process / SOP)

Acceptance

• Decision on (a) / (b) / (c)
• If skill/flag added: implement git-log-scan + spectra-archive-scan + AskUserQuestion surfacing
• If doc only: add rule reminder
• Test: simulate the 2026-05-04 case and verify new flow surfaces it

Source

• Triggering session: ai_martech_global_scripts #502 split (2026-05-04)
• Sister principle: IC_R011 — files sub-issues willingly, but not for already-shipped work

Cross-reference

In ai_martech_global_scripts:

• #536 closed retrospectively
• #537 closed retrospectively

---

Current Status

Phase: closed
Last updated: 2026-05-07 by idd-close

Resolution

• PR docs: idd-issue Step 4.8 Split Umbrella SOP — pre-flight scan before sub-issue file #38 merged → main
• docs option (c) — Step 4.8 Split Umbrella SOP added to idd-issue/SKILL.md

[kiki830621]

Diagnosis

Type

enhancement (process / SOP)

Analysis

#11 提出一個 process gap:在 split umbrella issue 為 N sub-issue 時,可能 file 已經 shipped 的 work — issue body 引述 ai_martech_global_scripts #502 案例(scope 1 + 2 在 4 天前 commit 7292219 已經做完,但 split session 仍 file 為 #536/#537)。

提出 3 個 design options:

• (a) 新 skill /idd-split-umbrella <issue#>(重)
• (b) flag /idd-issue --split-from <#>(中)
• (c) 純 documentation SOP reminder(輕)

Decision: 選 (c) docs-only,理由:

1. IDD 設計哲學:不在沒見過 N 個 instance 之前抽 abstraction(三 instance 出現再 refactor 出 helper)。目前只記錄 1 個 case (#502),不夠 evidence 證明需要 dedicated skill / flag
2. Split umbrella 本身是低頻操作 — 大多 issue 是 atomic,不會 split。新 skill / flag 對其他 callers 是 dead weight
3. 核心防範動作是 mental check + 簡單命令(git log --grep "#$UMBRELLA" + scan archive) — 寫進 SOP 即可,使用者背一次就會
4. idd-issue 已含 sister-sweep 機制(Step 4.7 IC_R011),類似精神已存在;split-time scan 可作為 idd-issue 的 doc-level 提醒,不需新 skill
5. 若未來累積 ≥3 個重複 occurrences,再 promote 為 skill / flag(自然演化)

Impact

檔案範圍 (1-2 file,純 docs):

檔案	改動
plugins/issue-driven-dev/skills/idd-issue/SKILL.md	在 Step 4.7 sister sweep 附近加 ## Split Umbrella SOP mini-section,含 git log scan + archive scan + 範例 trace
plugins/issue-driven-dev/CLAUDE.md (optional)	在 Skills 段落附近加一句 cross-link「split umbrella 前先 scan,見 idd-issue#split-umbrella-sop」

使用者流程衝擊: zero behavioral change in code — 改寫 prose,留 mental discipline trigger。

Strategy

Single PR,1-2 file,純 docs:

• A. idd-issue/SKILL.md 加新 sub-section ## Split Umbrella SOP (process reminder) 列:
  • When applies (split umbrella issue 為 N sub-issues 時)
  • Pre-flight commands:

    git log --oneline --grep "#$UMBRELLA" --since="<umbrella creation>"
    git log --oneline --since="<umbrella creation>" --grep="<spectra change name from body>"
    ls openspec/changes/archive/ | grep -i "<keyword from body>"

  • Decision rule:每 candidate sub-issue,若有 commit/archive match → AskUserQuestion「retroactive close vs file fresh」
  • 引 ai_martech_global_scripts #502 為歷史例
• B (optional). plugins/issue-driven-dev/CLAUDE.md 加 cross-link bullet 在 ## Skills table 之後

Complexity

Simple

Layer 1 命中:「主要 deliverable 是更新既有 prose 但不改 behavior」(option (c) docs-only 設計選擇)。1 file change, no code, no behavioral change, no cross-file dependency。

Layer 1 disqualifier 命中即跳過 Layer 2 / Layer P 評估。

NOTE about original 3-option decision:Plan tier 通常 trigger when「decision-heavy with 2+ valid approaches」。本 issue 確實有 3 options,但本 diagnose 已明確 pick (c)(reasoning above) → decision 已 made,implement 階段不再有 design space → drop 到 Simple。

Risks

• Discoverability — SOP 寫在 SKILL.md 內,使用者跑 /idd-issue 不一定看 SKILL.md (skill 的 prompt 才是 always-loaded context)。Mitigation:在 idd-issue 的 Step 4.7 sister sweep 旁邊放 inline 提醒(scan-before-file 與 sister-sweep 同類精神),sister sweep 是 mandatory step 必跑
• Effective only if user 用 /idd-issue build sub-issue — 若使用者用 gh issue create 直接建,SOP scope outside

Related

• IC_R011 (#525 ai_martech_global_scripts) — 同類 mechanical low-bar filing pattern,本 SOP 是 split-time variant
• 案例觸發:ai_martech_global_scripts #502 split (2026-05-04) → #536/#537 retroactive close

Vagueness Pre-check

• V1: 2 — issue body 列具體案例 (#502 → 7292219) + 3 design options (a/b/c) + acceptance checkboxes
• V4: 3 — Acceptance 含「decision on (a)/(b)/(c)」是 open question, diagnose 階段 pick (c) 後變確定

[Layer V: V1=2 V4=3, both axes ≤ 3, not triggered. Unattended mode confirmed.]

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

[Unattended mode — auto-skipped. Diagnosis 內提及 ai_martech_global_scripts #502 是 historical context (cross-repo, 已存在 issue),不是 sister concern surfacing。]

[kiki830621]

Implementation Complete

Checklist (synced from TaskList)

• A. idd-issue/SKILL.md Step 4.8 Split Umbrella SOP → commit 4962387
  • When-applies trigger heuristic
  • 4 pre-flight scan commands (commits / spectra archive / trailer scan)
  • AskUserQuestion 3-option (retroactive / skip / file fresh)
  • Audit trail format (### Pre-flight scan)
  • Historical case reference (ai_martech_global_scripts #502)
• [-] B. CLAUDE.md cross-link — won't fix: SKILL.md Step 4.8 is mandatory step in skill execution context (always loaded when /idd-issue runs), additional cross-link in CLAUDE.md adds redundancy without proportional discoverability gain. /idd-issue caller already gets prompted by Step 4.7+4.8 sequence.

Legend: - [x] done · - [-] won't fix

Changes

• 4962387 docs: idd-issue 加 Step 4.8 Split Umbrella SOP

Files Changed

 plugins/issue-driven-dev/skills/idd-issue/SKILL.md | 47 ++++++++++++++++++++++
 1 file changed, 47 insertions(+)

Scope Compliance

• ✅ 1 file change (對齊 plan + diagnose option (c))
• ✅ 純 docs,no code, no behavioral change
• ✅ 沒 invent abstraction (依 diagnose 5-reason rationale)

Next: verification pending (lightweight self-verify only — pure docs)

[kiki830621]

Verify

Mode: lightweight self-verify (純 docs prose insertion,1 file,docs option (c))

Checks

• Section placement correct — Step 4.8 在 Step 4.7 (Linked-Context Sister Sweep) 之後、Step 5 (回報並停止) 之前
• Required parts all present — When applies / Why mandatory / Pre-flight checks (4 commands) / AskUserQuestion 3-option / Audit trail format / Why SOP-only rationale / Historical case
• References correct — ai_martech_global_scripts #502 (historical case from [SOP] umbrella split flow should mandate commit log scan before filing sub-issues #11 body), #525 IC_R011 canonical (sister sweep precedent), #11 self-reference
• Markdown render clean — code blocks balanced, regex inside backticks not breaking GFM
• Scope discipline — 嚴格依 diagnose option (c),不 invent skill / flag

Verdict

PASS — 純 docs SOP,no code,no test plan needed (按 IDD Layer 1 Simple disqualifier - prose update)。

Sister observations

• 無 follow-up findings

[kiki830621]

Closing Summary

Problem

Split umbrella issue 為 N sub-issues 時可能 file 已 shipped 的 work — ai_martech_global_scripts #502 案例:scope 1+2 在 commit 7292219 (4 天前) 已做完,split session 仍 file 為 #536/#537,需要 retroactive close。Wasted ~10 min audit + noise in Open issue list。

Root Cause

Split umbrella 操作低頻但發生時容易踩坑。/idd-issue 既有 sister-sweep (Step 4.7 IC_R011) 是同類精神但只 cover linked-context,不掃 git log + spectra archive 找已 shipped 的 sub-scope。

Solution

idd-issue/SKILL.md 加 Step 4.8 Split Umbrella SOP (option (c) docs-only per diagnose option ranking)。

選 docs-only 而非 (a) 新 skill / (b) flag,理由:

1. IDD 紀律:「不在沒見過 N instance 之前抽 abstraction」(目前只 1 case #502)
2. Split umbrella 是低頻操作,新 skill / flag 對其他 callers 是 dead weight
3. 核心防範動作是 mental check + 4 個簡單命令 — 寫進 SOP 即可
4. 若未來累積 ≥3 occurrences 再 promote 為 skill / flag (自然演化)

SOP 內容:

• When-applies trigger heuristic
• 4 pre-flight scan commands (commits / spectra archive / trailer scan)
• AskUserQuestion 3-option (retroactive close / skip / file fresh)
• Audit trail format (### Pre-flight scan)
• Historical case reference

Verification

• Lightweight self-verify PASS:section placement 在 Step 4.7 之後 / Step 5 之前 (line 774);required parts 6/6 present (when-applies / why-mandatory / pre-flight commands / AskUserQuestion / audit trail / historical case);references 正確 (ai_martech_global_scripts #502, IC_R011 #525, self-ref [SOP] umbrella split flow should mandate commit log scan before filing sub-issues #11);markdown render clean
• 純 docs prose,no test plan needed (IDD Layer 1 Simple disqualifier)

Changes

• 4962387 docs: idd-issue 加 Step 4.8 Split Umbrella SOP ([SOP] umbrella split flow should mandate commit log scan before filing sub-issues #11)
• c68b9d0 (squash on main) PR docs: idd-issue Step 4.8 Split Umbrella SOP — pre-flight scan before sub-issue file #38 merged

Related

• IC_R011 ai_martech_global_scripts#525 (canonical mechanical low-bar filing pattern)
• ai_martech_global_scripts#502 (historical triggering case)