name: sdlc-sync description: 僅由 /sdlc-sync 指令叫用。把議題留言裡的決策整併回議題描述，並標記已整併的留言。 # sdlc-sync 新加入的人不必爬完整串留言，就能從議題描述知道現況。 這份檔案是流程正本。各平台的轉接檔只是指回這裡，不要把規則抄過去。 ## 輸入 一個議題編號。可能是需求議題，也可能是工作包議題。 ## 1. 讀議題與留言 需求議題用 `issue-extract`，工作包議題用 `wp-extract`： ``` node scripts/issue-extract.js --repo --index <編號> ``` 兩支都會給 `未處理留言數`。**那是這一輪要看的量**；已經標記過的留言不再處理。 接著讀留言本身。抽取契約只給數字不給內容，所以留言要另外拿： ``` node scripts/pr-comments.js --repo --index <編號> ``` 議題與 PR 都收得下：它先讀議題本身，是 PR 才會再去翻 review。純議題的 `類型` 是 `議題`， 留言的 `類型` 都是 `一般`。`已處理` 為 `true` 的跳過——那是前幾輪整併過的。 `已處理` 認的是**自己打的** `+1`。別人按讚是「我同意」，不是「這則已經收進描述了」。 ## 2. 挑出真正的決策 **不是每一則留言都要整併。** 逐則判斷它有沒有改變「這顆議題現在說的事」： - **要整併** — 改變了目標、範圍、做法、驗收標準；補上了原本沒寫的限制；推翻了描述裡的假設。 - **不整併** — 提問與答覆、進度回報、「收到」、與內容無關的討論、已經反映在描述裡的事。 判斷不了的**當成要整併**，然後在下一步問使用者——漏掉一個決策，描述就會繼續騙後面的人。 ## 3. 提出整併方案，讓使用者點頭 **先列出來再動手。** 對每一則要整併的留言，說明： - 它說了什麼（一句話） - 要併進**哪一段**（`總覽`／`目標`／`非目標`／`驗收標準`／`未決事項`…） - 那一段**改完長什麼樣** 然後一次問一題，兩個選項： - **整併** — 照你提的方案寫回去。 - **略過** — 這一則不併。**略過的留言保持未標記**，下次執行還會被提出來。 使用者要改你的寫法時，照他說的改。這一步是議題描述的最後一道關卡——寫進去之後， 後面的人就是拿它當事實。 ## 4. 逐段寫回 一段一段來。同一段有多則留言的決策就先合併成一份內容，一次寫回： ``` node scripts/comments-merge.js --repo --index <編號> \ --section <段落名> --content-file <暫存檔> --merged <該段的留言 id> --dry-run ``` `--content-file` 是**那一段改完的完整內容**（不含 `## 標題` 那一行）。腳本只換那一段， 其餘一字不動。 `--merged` 只放**真的被併進這一段**的留言 id。略過的不要放進去——放了就等於這則再也 不會被提出來。 試跑會印出改完的描述與將標記的留言。確認無誤後拿掉旗標再跑一次。 腳本先寫描述再標記，描述寫失敗就不標記。`SECTION_NOT_FOUND` 表示段落名與議題上的 `## 標題` 對不上，**不要改用別的段落硬塞**，回頭確認名稱。 ## 5. 回報 - 幾則留言、整併了幾則、略過幾則 - 改了哪幾段，各自併進了什麼 - 略過的那幾則是哪些（**要列出來**，讓使用者知道它們下次還會出現） **略過的留言會讓 `未處理留言數` 停在大於 0。** 那是刻意的——下次還要被提出來。但它也表示 `/sdlc-analyze` 與 `/sdlc-feat` 每次開始時都會再停一次。回報時要講明白這件事，讓使用者知道 那不是沒整併乾淨，而是他選了略過。 ## 接回原本的指令 這個指令常常不是使用者自己叫的，而是 `/sdlc-analyze` 或 `/sdlc-feat` 發現有未整併留言後 轉過來的。**整併完就直接接回去**，從原本那個指令被打斷的地方繼續，不要要求使用者重打一次。 接回去之前先重跑一次抽取（`issue-extract`／`wp-extract`），拿到的才是剛更新過的描述—— 接著用舊的那一份做事，這一整段就白做了。 ## 邊界 - 不自行決定要不要整併：方案一定先給使用者看過。 - 不整份重寫描述，只換談好的那幾段。 - 不標記略過的留言。 - 不刪除、不編輯任何留言——留言是誰說過什麼的紀錄，整併是把結論抄進描述，不是把原文搬走。 - 不因為整併而改變議題的狀態、標籤或指派。