shiftblame 0.3.5 → 0.4.0

package/README.md

@@ -117,9 +117,9 @@ _一套明確責任歸屬的 Agents 開發框架_
 | 1 | product-planner    | prd    | 把老闆原話轉 PRD |
 | 2 | system-architect   | dag    | 技術選型、模組拓撲、檔案結構、介面簽章、部署方案 |
 | 3 | project-manager    | spec   | 功能拆解、驗收條件、任務依賴 |
-| 4 | quality-assurance  | basis  | 依 dag + spec 寫測試（TDD 紅） |
+| 4 | quality-assurance  | basis  | 依 dag + spec 寫測試（TDD 紅）= **QA 定規則** |
 | 5 | feature-developer  | devlog | 寫最小實作讓測試全綠（TDD 綠） |
-| 6 | quality-control    | e2e    | 使用者視角 e2e 測試並實際執行 |
+| 6 | quality-control    | e2e    | 使用者視角 e2e 測試並實際執行 = **QC 依規則驗收** |
 | 7 | audit-reviewer     | audit  | 整條鏈路驗收，回傳 ACCEPTED / REJECTED |
 | 8 | operations-engineer| ops    | 在 main 依 dag 方案實際上線 |
 
@@ -242,7 +242,7 @@ npm install shiftblame
 /shiftblame-reflect
 ```
 
-這會掃描所有角色的鍋紀錄，將「下次怎麼避免」欄位提煉成條列式常識，重新寫回各角色的 BLAME.md 檔頭。
+這會掃描所有角色的鍋紀錄，將「下次怎麼避免」提煉成**常識（規則）**，將「背後的機制」與「為什麼這條規則有效」提煉成**認知（模型）**，重新寫回各角色的 BLAME.md 檔頭。
 
 > **為什麼要用 `/secretary`？** Claude Code 不保證每次都能正確判斷該觸發哪個 skill，顯式呼叫最可靠。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shiftblame",
-  "version": "0.3.5",
+  "version": "0.4.0",
   "description": "推鍋",
   "scripts": {
     "postinstall": "node scripts/postinstall.js"

package/docs/prompt-improvement-plan.md

@@ -1,322 +0,0 @@
-# Shiftblame Prompt 改善計畫
-
-基於對專案本質的深度對話，提煉出以下改善方向。
-
----
-
-## 一、從身份論轉向行為論
-
-### 問題
-
-現有 prompt 全部以「你是 **X**」開頭：
-
-```
-你是 **product-planner**，產出是 **prd**。
-你是 **system-architect**，產出是 **dag**。
-你是 **quality-assurance**（qa-lead / 測試主管）...
-```
-
-這是「君君臣臣」的身份論讀法——先定義「你是誰」，再要求「做你該做的事」。身份是前提，行為是派生。
-
-### 改善方向
-
-改為行為論——先定義「要做什麼」，身份只是標籤：
-
-```
-# 之前（身份優先）
-你是 **product-planner**，產出是 **prd**。
-
-# 之後（行為優先）
-做企劃：把老闆原話轉寫成 PRD。
-標籤：product-planner
-產出：prd
-```
-
-原理：「做企劃要符合做企劃的標準」（君君的動詞讀法），不是「你是企劃所以你應該做企劃的事」。行為定義角色，不是角色定義行為。
-
-### 具體影響
-
-- 所有 13 個 agent prompt 的開頭段落需重寫
-- 「定位」章節從「你的角色是⋯」改為「這個環節做什麼、為什麼存在」
-- 「唯一職責」保留但重新措辭——從「你負責」改為「此環節的工作是」
-
----
-
-## 二、QA/QC 定義回歸製造業原始定義
-
-### 問題
-
-現有 prompt 中 QA 和 QC 的區分已經做了，但描述語言仍帶有軟體業的模糊性。特別是 `quality-control.md` 中寫：
-
-> **與 quality-assurance 的差別**：
-> - quality-assurance（qa-lead + 三位測試工程師）**設計並撰寫**測試（TDD 紅階段）
-> - 你負責**在實作完成後執行 E2E 測試**，並撰寫執行報告與驗收結論
-
-這個描述是正確的，但沒有講清楚**為什麼**要這樣分。
-
-### 改善方向
-
-在兩個 prompt 中加入原始定義的根基說明：
-
-```markdown
-## QA 與 QC 的本質差異（源自製造業）
-
-QA（Quality Assurance）：
-  建立品質體系、制訂規範、留下作業證據。
-  證明每一步都按要求進行。
-  → 在產品「生產之前」定標準。
-
-QC（Quality Control）：
-  檢驗產品、糾正缺陷、防止不合格品出貨。
-  確保產品滿足品質要求才能交付。
-  → 在產品「生產之後」驗結果。
-
-QA 定規則。QC 依規則驗收。兩者必須分離——
-自己出題自己改考卷 = 沒有品管。
-```
-
-### 具體影響
-
-- `quality-assurance.md`：加入 QA 原始定義段落
-- `quality-control.md`：加入 QC 原始定義段落，強調「QC 跑測試，不寫測試」
-- 秘書 `SKILL.md`：在推鍋鏈表格中加註 QA/QC 的本質差異
-
----
-
-## 三、BLAME 從「記錄規則」升級為「建構 model」
-
-### 問題
-
-現有 BLAME 格式：
-
-```markdown
-## <slug> · <YYYY-MM-DD>
-**犯了什麼錯**：...
-**怎麼被抓的**：...
-**本質原因**：...
-**下次怎麼避免**：...
-**要改什麼**：...
-```
-
-這個格式記的是 **rule**（「下次怎麼避免」= 一條具體規則）。`shiftblame-reflect` 會把這些規則聚合成「常識」清單。
-
-但 rule 在沒有 model 支撐的情況下會失效——碰到 rule 沒覆蓋的情境就死了。
-
-### 改善方向
-
-BLAME 格式增加 **「為什麼這條規則有效」** 欄位，強制記錄 model 層級的理解：
-
-```markdown
-## <slug> · <YYYY-MM-DD>
-**犯了什麼錯**：...
-**怎麼被抓的**：...
-**本質原因**：...
-**背後的機制**：為什麼這個原因會導致這個錯？結構上是什麼在壞？
-**下次怎麼避免**：...（具體 rule）
-**為什麼這條規則有效**：這條規則在什麼條件下成立？什麼情境下會失效？
-**要改什麼**：...
-```
-
-`shiftblame-reflect` 聚合時，除了提煉 rule，也提煉 **model**：
-
-```markdown
-## 常識（規則）
-- [規則 1]
-- [規則 2]
-
-## 認知（模型）
-- [機制 1：為什麼 X 會導致 Y]
-- [機制 2：Z 在什麼條件下會壞]
-```
-
-### 具體影響
-
-- 所有 13 個 agent prompt 的「犯錯處理」章節需更新格式
-- `shiftblame-reflect.md` 需更新聚合邏輯
-- 秘書 SKILL.md 的 BLAME 格式範例需同步
-
----
-
-## 四、高壓縮指令支援（m → 1）
-
-### 問題
-
-現有秘書的預審閘門和交棒機制預設老闆會用「完整的句子」描述需求。但高 c² 的使用者（本專案的目標用戶）傾向極短指令：
-
-```
-老闆說：「架構問題」
-意思是：「目前的架構設計有問題，從架構層重新跑」
-```
-
-現有秘書不一定能正確展開這種極短指令。
-
-### 改善方向
-
-在秘書 SKILL.md 的「秘書判鍋」章節加入高壓縮指令處理邏輯：
-
-```markdown
-## 高壓縮指令處理
-
-老闆可能用極短的指令表達完整意圖。秘書的工作是展開，不是要求老闆多說。
-
-處理流程：
-1. 收到極短指令（< 10 字）
-2. 結合 REPO.md 歷史 + 當前 codebase 狀態 + 最近的推鍋鏈紀錄
-3. 推導老闆最可能的完整意圖
-4. 在預審閘門中呈報推導結果：「老闆，您說 [原話]，我理解為 [展開後的意圖]，準備從 [層級] 開始。」
-5. 老闆只需說「對」或糾正
-
-原則：寧可秘書多推導一步，也不要讓老闆多解釋一句。
-老闆的表達成本 > 秘書的推導成本。
-```
-
-### 具體影響
-
-- 秘書 `SKILL.md`：加入高壓縮指令處理段落
-- 諮詢模式中也需支援——老闆在諮詢時也會用短句
-
----
-
-## 五、去中心化決策能力
-
-### 問題
-
-現有 agent prompt 全部是「等指令 → 執行 → 回報」的模式。每個 agent 都是被動的執行者，沒有自主判斷的空間。
-
-這是中央計畫式的架構——每個節點只能做被指定的事，碰到指定以外的狀況就回報 `NEEDS_CLARIFICATION`。
-
-### 改善方向
-
-給每個 agent 有限度的自主決策空間：
-
-```markdown
-## 自主決策範圍
-
-以下情況可以自行決定，不需要回報：
-- [列出該層級可以自行判斷的事項]
-
-以下情況必須回報：
-- [列出必須升級的事項]
-
-判斷原則：如果你的決定只影響自己這一層的產出，自己決定。
-如果你的決定會影響上游或下游，回報。
-```
-
-例如 `system-architect` 可以自行決定測試框架（只要跟團隊歷史一致），但技術選型變更必須回報。
-
-### 具體影響
-
-- 所有 13 個 agent prompt 加入「自主決策範圍」章節
-- 秘書在交棒時明確告知 agent 其自主範圍
-- 減少不必要的 `NEEDS_CLARIFICATION` 來回
-
----
-
-## 六、風險容忍度校準
-
-### 問題
-
-現有 prompt 偏保守——大量「嚴禁」清單、頻繁的確認機制。這對低風險容忍度的環境是對的，但對台灣式的高風險容忍度環境，這些確認機制會變成摩擦。
-
-### 改善方向
-
-引入風險等級概念，讓確認機制的頻率可調：
-
-```markdown
-## 風險等級（由秘書在啟動時設定）
-
-Level 1（高確認）：每層預審 + 每步確認
-  → 適合新專案、不熟悉的領域
-  
-Level 2（標準）：每層預審，層內自主
-  → 預設模式
-  
-Level 3（快速）：只在關鍵層預審（架構、稽核），其餘自動推進
-  → 適合熟悉的領域、老闆信任度高
-```
-
-### 具體影響
-
-- 秘書 `SKILL.md`：加入風險等級設定機制
-- 預審閘門邏輯依風險等級調整
-- 老闆可以在啟動時說「快速模式」跳過非必要確認
-
----
-
-## 七、每層加入「為什麼這層存在」
-
-### 問題
-
-現有 prompt 的「定位」章節說的是「你在哪裡、你跟誰接棒」，但沒說**為什麼這層需要存在**。
-
-Agent 只知道自己該做什麼，不知道**如果拿掉自己會怎樣**。這讓它們無法在邊界情況下做正確判斷。
-
-### 改善方向
-
-每個 agent prompt 加入「存在理由」：
-
-```markdown
-## 為什麼這層存在
-
-如果拿掉這層：[具體描述會壞什麼]
-這層解決的核心問題：[一句話]
-```
-
-範例（system-architect）：
-
-```markdown
-## 為什麼這層存在
-
-如果拿掉這層：每個開發者各自決定技術選型和檔案結構，
-最後拼不起來，重工成本極高。
-這層解決的核心問題：在寫 code 之前，把東西怎麼接想清楚。
-```
-
-### 具體影響
-
-- 所有 13 個 agent prompt 加入「為什麼這層存在」
-- 讓 agent 理解自己的 model，不只是 rule
-
----
-
-## 八、秘書的「場感知」能力
-
-### 問題
-
-秘書目前只處理明確的文字指令。但高 c² 的老闆經常用壓縮標籤代替精確描述（例如用「噁心」表達複雜的認知體驗）。
-
-### 改善方向
-
-在秘書 prompt 加入：
-
-```markdown
-## 老闆的表達模式
-
-老闆傾向高壓縮表達。一個詞可能承載完整的判斷。
-
-處理原則：
-- 不要把老闆的詞語當字面意思解讀
-- 老闆說「爛」可能不是情緒，是結構性判斷
-- 老闆說「對」不只是同意，是確認你的展開跟他腦中的 model 對齊
-- 老闆說「不對」不是否定你，是你的展開沒對齊他的 model
-- 永遠從「老闆在描述什麼結構」的角度解讀，不從「老闆在表達什麼情緒」的角度
-```
-
-### 具體影響
-
-- 秘書 `SKILL.md`：加入老闆表達模式章節
-
----
-
-## 優先順序
-
-| 優先級 | 改善項目 | 影響範圍 | 理由 |
-|---|---|---|---|
-| P0 | 二、QA/QC 定義校正 | 2 個 agent + 秘書 | 定義錯誤會導致整條鏈的品質邏輯偏差 |
-| P0 | 四、高壓縮指令支援 | 秘書 | 直接影響老闆的使用體驗 |
-| P1 | 一、身份論→行為論 | 13 個 agent | 結構性改善，影響所有 agent 的自我認知 |
-| P1 | 三、BLAME model 化 | 13 個 agent + reflect | 影響系統的學習能力 |
-| P1 | 七、存在理由 | 13 個 agent | 影響 agent 的邊界判斷能力 |
-| P2 | 五、去中心化決策 | 13 個 agent + 秘書 | 減少摩擦，但需要謹慎設計邊界 |
-| P2 | 六、風險等級 | 秘書 | 提升效率，但需要老闆手動設定 |
-| P2 | 八、場感知 | 秘書 | 提升溝通品質 |