diff --git a/references/delegation.md b/references/delegation.md new file mode 100644 index 0000000..ec9fca3 --- /dev/null +++ b/references/delegation.md @@ -0,0 +1,57 @@ +# 委派判準 + +流程正本裡標著〔可委派〕的步驟,是照這份判準挑出來的。**四條全部成立才可委派**; +任何一條不成立就不標,那一步一律自己做。 + +這份是規則正本,流程正本指名讀它,不把規則抄過去——抄過去就會有兩份各自演化的判準。 + +## 判準 + +1. **產出是可驗證的成品** — 交回來的東西呼叫端看得出對不對:一個英文 kebab 字串、 + 一份日期表、一份疑點清單、一份 HTML。說不出「拿回來的該長什麼樣」的步驟不可委派, + 因為呼叫端沒有辦法判斷它做完了沒有。 +2. **步驟中不會詢問使用者** — **硬排除**。子代理問不到使用者,一旦卡在提問就只能自行 + 決定,而它決定的那件事使用者從頭到尾不會知道。逐題問到共識、問來源分支、認不出語言 + 就停下來問——這類步驟一律不標,無論它們看起來多像例行公事。 +3. **失敗能被呼叫端偵測** — 交不出東西、交回來的形狀不對,主流程當場看得出來並接手。 + 失敗只會表現成「結果怪怪的」而不會表現成「失敗」的步驟不可委派。 +4. **只產出草稿或唯讀結果,不直接寫入 Gitea 或 git** — **硬排除**。理由不是子代理做不好, + 而是**它的失敗沒有人看著**:備妥工作樹失敗會中止整個領取,實際提交失敗會留下半套 + git 歷史,這兩種都需要當場有人判斷下一步。 + +## 怎麼委派 + +標記寫成標題後綴 `〔可委派〕`,並以**能力描述**說明怎麼做,不指名任何平台的工具: + +> 這一步只在意結果;你的環境若能把工作交給子代理,就交出去,只把結果帶回來;不能就自己做。 + +子代理是平台專屬能力,而流程正本必須保持平台中立。能力描述對不支援的平台是自然降級, +同一份正本兩邊都讀得通,不需要維護兩份。**不要把它改寫成工具名**——那會讓正本綁死在 +某一個助理上。 + +委派與否不改變產出:兩條路的結果必須一樣,差別只在中間產物留不留在主脈絡裡。 + +## 部分委派 + +一個步驟裡只有一半合判準時,**標記照下,並在該步寫明哪一半不委派**。這比整步不標好—— +不標的話那一半的中間產物照樣塞滿主脈絡;也比整步委派安全,因為第四條是硬排除。 + +目前有三步是這個形狀:兩份圖解總覽(產出 HTML 可委派,寫回議題的 `issue-update` 不委派) +與分批提交(方案計算可委派,實際跑 `commit-split.js` 不委派)。 + +## 目前標記為〔可委派〕的步驟 + +這張表與正本上的標記互為正本,**兩邊由資產測試雙向綁住**。改一邊就要改另一邊, +否則測試會擋下來——沒有這條斷言,兩邊會漂開,而漂開時不會有任何東西報錯。 + +| 正本 | 步驟 | 委派範圍 | +| --- | --- | --- | +| `sdlc-plan` | 產生圖解版總覽 | 產出 HTML;寫回議題不委派 | +| `sdlc-analyze` | 對四份清單列出疑點 | 全步 | +| `sdlc-analyze` | 算出截止日 | 全步 | +| `sdlc-analyze` | 產生分析版的圖解總覽 | 產出 HTML;寫回議題不委派 | +| `sdlc-feat` | 把議題標題翻成英文 | 全步 | +| `sdlc-feat` | 分批提交 | 方案計算;實際提交不委派 | + +`sdlc-sync`、`sdlc-fix` 與 `sdlc-report` 目前沒有可委派的步驟:前兩者每一步都在問使用者 +或寫入 Gitea,後者只有一支唯讀腳本,委派出去省不到什麼。