tea-sdlc/prompts/sdlc-plan.md

name: sdlc-plan description: 僅由 /sdlc-plan 指令叫用。把一段口語需求轉成結構化的需求議題，寫入 Gitea。

sdlc-plan

把使用者給的一段需求，變成一顆結構完整、下游指令讀得動的需求議題。

這份檔案是流程正本。各平台的轉接檔只是指回這裡，不要把規則抄過去。

輸入

使用者給的東西可能是下列任一種，也可能三種混用：

• 自由文字 — 一段口語描述。
• 規格檔 — 一個檔案路徑，內容是既有的規格或筆記。
• 議題編號 — 既有議題的編號，用來補充脈絡或作為延伸的起點。

先把三種來源讀齊，再開始問問題。規格檔用檔案讀取工具讀；議題編號用 scripts/issue-extract.js 取（若該腳本尚未可用，改用 scripts/issue-create.js 以外的 既有讀取途徑，並在摘要中註明資料來源）。

計時範圍

這份正本把整個 /sdlc-plan 的耗時記成兩段，合起來就是這道指令實際花掉的時間：

• 議題建立之前 — 在「記下開始時間」記下起點，在「補登規劃時間，然後起錶」補上去。 議題還不存在，沒有標的可起錶。
• 議題建立之後 — 在「補登規劃時間，然後起錶」起錶，在「停錶並回報」停錶。

起與停都寫在這一份裡，錶不跨階段跑：跑完就去開會而錶跑一整天，報表當場失真。 反過來，別顆議題上的錶一律不碰——那一段時間該記在哪顆議題上只有使用者知道。

〔可委派〕的意思

標題後綴 〔可委派〕 的步驟只在意結果：你的環境若能把工作交給子代理，就交出去， 只把結果帶回來；不能就自己做。 沒有這個後綴的步驟一律自己做。

怎麼挑、為什麼這樣挑，見 references/delegation.md——判準只有那一份，這裡不複述。

步驟

1. 記下開始時間

讀齊輸入、逐項詢問、組出議題內容，往往是整個 plan 最耗時的一段，而它發生在議題建立 之前——那時候沒有標的可起錶。所以先把此刻的時間記下來，等議題建立之後補登上去：

node -e "console.log(new Date().toISOString())"

記下它，一路帶到「補登規劃時間，然後起錶」那一步。不要憑印象回推：補登的長度就是 報表上規劃階段的數字。

2. 讀齊輸入，列出還缺什麼

把九個段落逐一對照使用者給的材料，列出哪些段落已經有依據、哪些沒有。

3. 逐項詢問

一次問一題，等使用者回答完再問下一題，讓他能看著前一題的答案回答下一題。

每一題都附上你的建議與理由，讓使用者多數時候只要點頭；同時保留讓他自己寫答案的餘地。

未獲得答覆的欄位不得自行編造。 使用者沒說過的目標、沒提過的驗收標準，一個字都不能自己 填。問不到就放進「未決事項」，那一段本來就是給未決的東西用的。

4. 組出議題內容

套用 templates/requirement-issue.md，依序填滿九個段落：

1. 總覽 — 一句話講完這件事在做什麼，讓非技術的利害關係人不必讀完技術細節。圖解版總覽的 連結此時先留空，由後續流程回填。
2. 背景 — 不超過三行。為什麼現在要做這件事。
3. 目標 — 可量測。寫得出「怎樣算達成」才算數。
4. 非目標 — 明列這次不做什麼，用來抵抗範圍蔓延。
5. 領域名詞表 — 這份需求裡會反覆出現的詞，各給一行定義，讓團隊對同一個詞的理解一致。
6. 流程圖 — 見下方「流程圖的限制」。
7. 驗收標準 — 逐條列出，每一條都要能被驗證。
8. 影響範圍 — 會動到哪些 repo、哪些既有功能。
9. 未決事項 — 問不到答案、或需要他人拍板的事。

5. 挑標籤

先用 scripts/labels-list.js --repo <owner/name> 取得該 repo 的既有標籤，只能從這份清單裡 挑。找不到合適的就不貼。不得自行建立新標籤 —— 標籤體系由專案維護者決定，不該在多個 repo 之間長出雜草。

6. 先試跑，再寫入

把組好的內容寫到一個暫存檔，然後：

node scripts/issue-create.js --repo <owner/name> --title "<標題>" --body-file <暫存檔> \
  --labels "<標籤1,標籤2>" --dry-run

--dry-run 會印出將要送出的請求而不真的寫入。確認無誤後拿掉該旗標再跑一次。

同一段需求重跑不會產生第二顆議題：issue-create 以標題查重，發現同名議題就回傳既有那一顆 並把 created 設為 false。

7. 補登規劃時間，然後起錶

議題有了，計時才有標的。先補登、再起錶，兩步指向同一顆議題。

先把「記下開始時間」到議題建立那一段補上去：

node scripts/time-log.js --repo <owner/name> --index <編號> --since <記下的開始時間> --dry-run

長度由腳本自己算，不必自己做減法，也不會讓兩邊的時鐘各算一次。終點看議題是不是這一輪 建立的：是就補到議題建立那一刻，不是（對既有議題重跑）就補到現在——那一輪的 規劃時間照樣要進報表。確認無誤後拿掉 --dry-run 再跑一次。

不設時間上限，照實補登。 中途去開會的那兩個小時會一起被算進去，這是刻意的：換來 這個流程不必為此多長一題出來問使用者。時間記多了看得出來，記不到就永遠找不回來。

補登完才起錶：

node scripts/timer.js --repo <owner/name> --index <編號> --dry-run

一樣先試跑，確認無誤後拿掉 --dry-run 再跑一次。

順序不能反過來：錶一旦跑在這顆議題上，time-log 就會跳過不補——那一段已經有錶在記了， 再補一次會與錶涵蓋的區間重疊。重跑是累計不是覆蓋，每一輪各記一筆，報表上加總起來 才是這顆議題真正花掉的規劃時間。

錶已經跑在別顆議題上時起錶會被擋下（STOPWATCH_ON_OTHER_ISSUE）。照實告訴使用者 是哪一顆，請他自己去停，不要代勞：那一段時間該記在哪顆議題上只有他知道。順帶說明 停錶不會動到任何既有的工作樹——碼錶只管時間、工作樹只管檔案。

8. 產生圖解版總覽 〔可委派〕

套用 templates/overview-artifact.html，把議題的總覽、目標與流程圖填成一份可以直接投影的 網頁。這一份是給非技術的利害關係人看的：他們不必讀完技術細節就知道這件事在做什麼。

模板的佔位對應如下，樣式不要動——版面與內容分開，改一邊不必碰另一邊：

• {{標題}} 需求議題標題
• {{來源議題}} 指回議題的連結
• {{總覽}} 一句話總覽
• {{目標}} 目標，逐條包成 <li>
• {{流程圖}} 流程圖的 Mermaid 原始碼（不含圍欄，圍欄是議題 markdown 用的）
• {{工作包全景}} 規劃階段還沒有工作包，填空字串；這一段由分析階段補上
• {{頁尾}} 產生時間與產生者

若執行環境能把 HTML 發佈成可分享的網址，就發佈；不能的話存成檔案，把路徑當成網址用。

委派的是產出那份 HTML；拿到網址之後寫回議題那一步不委派（判準第四條）。

拿到網址後寫回議題：

node scripts/issue-update.js --repo <owner/name> --index <編號> --overview-url <網址>

它把連結以固定前綴寫成總覽段落裡的一行，重跑時就地更新同一行，不會長出第二個連結； 議題原本的 markdown 白話總覽一字不動——網頁是補充，不是取代。連結旁會自動附上 「此連結預設為私有，組織外無法開啟」，因為讀到的人多半會想轉寄給組織外的人。

9. 停錶並回報

回報之前先停錶，這一段計時到此為止：

node scripts/timer.js --repo <owner/name> --index <編號> --stop

它只停這一顆上的錶。錶本來就沒在跑不算失敗（碼錶已停 會是 false 並附一句 說明），回報照樣做完。

把議題編號與網址告訴使用者。不要把整份議題內容再貼一次 —— 連結點進去就看得到。

流程圖的限制

用 Mermaid 的 flowchart。節點數上限 12，每個節點的文字上限 8 字。

超過就拆成多張圖，或者乾脆不畫 —— 一張塞了二十個節點的圖，比沒有圖更難懂。

節點文字寫該步驟在做什麼，不要寫成編號或代號。

模板的 {{流程圖}} 要填入完整的內容，兩種形式擇一：

• 要畫：一個或多個完整的 ```mermaid 圍欄區塊。
• 不畫：只在超過上限拆不開、或畫了不會比文字更清楚時才選這個，填一行說明為什麼不畫（例如「流程為單一直線，畫圖無助理解」），不要加圍欄。

圍欄寫在填入的內容裡而不是模板裡，否則不畫圖時會留下一個空的 mermaid 區塊， 在議題頁上是一塊渲染失敗的紅字。

邊界

• 不修改使用者的專案檔案。這個流程只讀輸入、寫 Gitea 議題。
• 不建立標籤、不建立 Milestone、不建立專案看板。
• 不關閉或刪除任何既有議題。
• 規劃階段本身已含問題釐清，因此寫入 Gitea 前不再設額外的確認點；--dry-run 就是那道關卡。
• 計時只動這顆需求議題：在它上面起錶、在它上面停錶、把規劃時間補登在它上面。 不停別顆議題上的錶，被別顆的錶擋下時交還給使用者決定，不繞過去。