feat: 移除計時並停用報表預覽
This commit is contained in:
+15
-163
@@ -3,178 +3,30 @@ description: 僅由 /sdlc-plan 指令叫用。把一段口語需求轉成結構
|
||||
|
||||
# sdlc-plan
|
||||
|
||||
把使用者給的一段需求，變成一顆結構完整、下游指令讀得動的需求議題。
|
||||
|
||||
這份檔案是流程正本。各平台的轉接檔只是指回這裡，不要把規則抄過去。
|
||||
|
||||
## 輸入
|
||||
|
||||
使用者給的東西可能是下列任一種，也可能三種混用：
|
||||
|
||||
- **自由文字** — 一段口語描述。
|
||||
- **規格檔** — 一個檔案路徑，內容是既有的規格或筆記。
|
||||
- **議題編號** — 既有議題的編號，用來補充脈絡或作為延伸的起點。
|
||||
|
||||
先把三種來源讀齊，再開始問問題。規格檔用檔案讀取工具讀；議題編號用
|
||||
`scripts/issue-extract.js` 取（若該腳本尚未可用，改用 `scripts/issue-create.js` 以外的
|
||||
既有讀取途徑，並在摘要中註明資料來源）。
|
||||
|
||||
## 計時範圍
|
||||
|
||||
這份正本把整個 /sdlc-plan 的耗時記成兩段，合起來就是這道指令實際花掉的時間：
|
||||
|
||||
- **議題建立之前** — 在「記下開始時間」記下起點，在「補登規劃時間，然後起錶」補上去。
|
||||
議題還不存在，沒有標的可起錶。
|
||||
- **議題建立之後** — 在「補登規劃時間，然後起錶」起錶，在「停錶並回報」停錶。
|
||||
|
||||
起與停都寫在這一份裡，**錶不跨階段跑**：跑完就去開會而錶跑一整天，報表當場失真。
|
||||
反過來，別顆議題上的錶一律不碰——那一段時間該記在哪顆議題上只有使用者知道。
|
||||
|
||||
## 〔可委派〕的意思
|
||||
|
||||
標題後綴 `〔可委派〕` 的步驟只在意結果：**你的環境若能把工作交給子代理，就交出去，
|
||||
只把結果帶回來；不能就自己做。** 沒有這個後綴的步驟一律自己做。
|
||||
|
||||
怎麼挑、為什麼這樣挑，見 `references/delegation.md`——判準只有那一份，這裡不複述。
|
||||
把自由文字、規格檔或既有議題整理成需求議題。
|
||||
|
||||
## 步驟
|
||||
|
||||
### 1. 記下開始時間
|
||||
|
||||
讀齊輸入、逐項詢問、組出議題內容，往往是整個 plan 最耗時的一段，而它發生在議題建立
|
||||
**之前**——那時候沒有標的可起錶。所以先把此刻的時間記下來，等議題建立之後補登上去：
|
||||
1. 讀齊輸入，列出九個段落中已有依據與缺漏。
|
||||
2. 一次問一題補齊缺漏；未獲回答的內容放入「未決事項」，不得自行編造。
|
||||
3. 套用 `templates/requirement-issue.md`，填入總覽、背景、目標、非目標、領域名詞表、流程圖、驗收標準、影響範圍與未決事項。
|
||||
4. 用 `scripts/labels-list.js` 取得既有標籤，只能選既有標籤。
|
||||
5. 寫入前先執行：
|
||||
|
||||
```
|
||||
node -e "console.log(new Date().toISOString())"
|
||||
node scripts/issue-create.js --repo <owner/name> --title "<標題>" --body-file <暫存檔> --labels "<標籤>" --dry-run
|
||||
```
|
||||
|
||||
記下它，一路帶到「補登規劃時間，然後起錶」那一步。**不要憑印象回推**：補登的長度就是
|
||||
報表上規劃階段的數字。
|
||||
確認內容後移除 `--dry-run` 實跑。重跑以標題查重，不建立重複議題。
|
||||
|
||||
### 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. 產生圖解版總覽 〔可委派〕
|
||||
|
||||
依 `references/artifact-contract.md` 從需求議題抽取結果組成 `schemaVersion: 1` JSON，
|
||||
執行 `node scripts/overview-render.js` 產生自包含 HTML 與 manifest。HTML 只給使用者檢視，
|
||||
不取代需求議題的詳細內容。若平台有 preview 能力就使用它；否則以短命 Node server
|
||||
服務 `.tmp/` 檔案供瀏覽器截圖。只有真正可用的 preview URL 才執行既有
|
||||
`node scripts/issue-update.js --overview-url <網址>`。
|
||||
產出 HTML 可委派；預覽截圖、附件上傳與任何 `issue-update` 寫回都不委派，由主流程
|
||||
執行並處理錯誤。
|
||||
|
||||
規劃階段沒有工作包，因此 `workPackages` 為空陣列，不產生工作包依賴圖。
|
||||
|
||||
### 9. 停錶並回報
|
||||
|
||||
回報之前先停錶，這一段計時到此為止：
|
||||
|
||||
```
|
||||
node scripts/timer.js --repo <owner/name> --index <編號> --stop
|
||||
```
|
||||
|
||||
它**只停這一顆**上的錶。錶本來就沒在跑不算失敗（`碼錶已停` 會是 `false` 並附一句
|
||||
說明），回報照樣做完。
|
||||
|
||||
把議題編號與網址告訴使用者。不要把整份議題內容再貼一次 —— 連結點進去就看得到。
|
||||
## 流程圖的限制
|
||||
|
||||
流程圖的抽象節點與邊保存於 JSON，由 renderer 重新產生 SVG；議題若需要保存圖表，
|
||||
由同一個 renderer 產生 Mermaid。節點數超過 12 或文字超過 8 字時拆圖或記錄
|
||||
`omitted` 原因，不由模型任意壓縮語意。
|
||||
流程圖只保留抽象節點與邊的文字描述；本流程不產生 HTML、SVG、manifest、截圖、附件或平台 preview。
|
||||
|
||||
## 邊界
|
||||
|
||||
- 不修改使用者的專案檔案。這個流程只讀輸入、寫 Gitea 議題。
|
||||
- 不建立標籤、不建立 Milestone、不建立專案看板。
|
||||
- 不關閉或刪除任何既有議題。
|
||||
- 規劃階段本身已含問題釐清，因此寫入 Gitea 前不再設額外的確認點；`--dry-run` 就是那道關卡。
|
||||
- 計時只動這顆需求議題：在它上面起錶、在它上面停錶、把規劃時間補登在它上面。
|
||||
**不停別顆議題上的錶**，被別顆的錶擋下時交還給使用者決定，不繞過去。
|
||||
|
||||
## Artifact 產物規則
|
||||
|
||||
圖解總覽不再套用 HTML 模板或依賴 Mermaid CDN。若此階段需要產生預覽，
|
||||
先依 `references/artifact-contract.md` 組成需求級 JSON，再執行
|
||||
`node scripts/overview-render.js`。HTML、SVG 與 manifest 只寫入 `.tmp/`；
|
||||
只有真正可用的 preview URL 才能使用既有 `--overview-url` 回寫。規劃階段沒有
|
||||
工作包時，`workPackages` 必須是空陣列，工作包全景不產生。
|
||||
- 不修改使用者專案檔案。
|
||||
- 不建立標籤、Milestone 或專案看板。
|
||||
- 不關閉或刪除既有議題。
|
||||
- 不產生任何預覽或 artifact。
|
||||
- 回報議題編號與網址，不重貼全文。
|
||||
|
||||
Reference in New Issue
Block a user