wicttor/pwrl

PWRL 規劃 — 純技能編排器

建立可持續交付執行的耐用實作計畫。編排一系列確定性的微技能管道：範圍界定 → 研究 → 設計 → 產生。無代理依賴，無備援路徑。

目的

計畫在執行之前捕捉決策、結構與方法。它們可以實現：

• 清晰的範圍與成功標準
• 已識別的風險與依賴關係
• 具體的實作單元及其驗收標準
• 透過相關學習經驗達成的知識重用
• 確信工作不會偏離軌道

核心工作流程：四階段管道

輸入（任務描述）
  ↓
第一階段：範圍界定（pwrl-plan-scope）
  → 收集脈絡、驗證領域、引導需求
  → 輸出：已界定脈絡的工件
  ↓
第二階段：研究（pwrl-plan-research）
  → 發現模式、識別風險、建議外部研究
  → 輸出：研究發現工件
  ↓
第三階段：設計（pwrl-plan-design）
  → 分解為單元、繪製依賴關係、評估複雜度
  → 輸出：包含單元分解的設計工件
  ↓
第四階段：產生（pwrl-plan-generate）
  → 選擇層級、渲染計畫、嵌入學習經驗、儲存至 docs/plans/
  → 輸出：儲存至檔案的最終計畫文件
  ↓
輸出（準備好執行的計畫檔案）

階段詳細說明

第一階段：範圍界定（pwrl-plan-scope）

目的： 規劃工作流程的進入點。收集脈絡、檢查現有計畫與學習經驗、驗證領域，並回傳已界定脈絡的物件。

微技能： pwrl-plan-scope

輸入：

• 使用者提供任務描述、需求文件或目標
• 空白輸入會提示使用者：「您想要規劃什麼？」

處理流程：

1. 檢查 docs/plans/ 中是否存在現有計畫；建議繼續/檢視/封存/刪除/新建
2. 驗證領域（軟體 vs. 非軟體）
3. 引導建立問題框架、預期行為、成功標準
4. 搜尋 docs/learnings/INDEX.md 以尋找相關學習經驗
5. 搜尋 docs/requirements/ 和 docs/brainstorms/ 以尋找相符文件
6. 與使用者確認脈絡
7. 詢問互動模式：
   • 詳細： 每個階段逐步互動（檢視、確認、調整）
   • Yolo： 從第一階段到第四階段全自動化，僅最後確認
8. 產生包含互動模式的範圍界定工件

輸出： 已界定脈絡的工件，包含：

• 問題框架、預期行為、成功標準
• 相關學習經驗（高相關性）
• 已識別的學習缺口
• 找到的需求
• interaction_mode（詳細或 yolo）

參閱： pwrl-plan-scope/SKILL.md 了解詳細工作流程

第二階段：研究（pwrl-plan-research）

目的： 發現本地模式、技術棧和高風險領域。必要時建議外部研究。

微技能： pwrl-plan-research

輸入： 來自第一階段的已界定脈絡工件

處理流程：

1. 從 package.json、Dockerfile、程式碼庫結構檢測技術棧
2. 發現本地模式（架構、非同步風格、測試、組織方式）
3. 識別高風險領域（安全性、效能、遷移、分散式系統、合規性）
4. 針對高風險領域建議外部研究（可選）
5. 整合相關學習經驗的洞察
6. 彙編研究發現

輸出： 研究工件，包含：

• 技術棧檢測結果
• 已識別的本地模式
• 風險領域與建議
• 外部研究發現（如有執行）
• 學習經驗整合備註

參閱： pwrl-plan-research/SKILL.md 了解詳細工作流程

第三階段：設計（pwrl-plan-design）

目的： 將工作分解為實作單元、識別依賴關係與風險、評估複雜度。

微技能： pwrl-plan-design

輸入： 已界定脈絡 + 研究發現

處理流程：

1. 從成功標準和風險領域識別工作單元
2. 繪製單元間的依賴關係（拓撲排序）
3. 檢測循環依賴；提示進行重構
4. 建立風險緩解單元
5. 為複雜工作流程（5 個以上單元）產生 Mermaid 圖表
6. 評估複雜度（低/中/高）
7. 估算工作量
8. 與使用者確認分解結果

輸出： 設計工件，包含：

• 實作單元（U1, U2, ..., UX），附測試場景與驗收標準
• 依賴圖與拓撲排序
• 風險緩解措施
• Mermaid 圖表（如複雜）
• 複雜度評估與工作量估算

參閱： pwrl-plan-design/SKILL.md 了解詳細工作流程

第四階段：產生（pwrl-plan-generate）

目的： 選擇層級（快速/標準/深入）、使用層級範本渲染計畫、嵌入學習經驗、儲存至 docs/plans/。

微技能： pwrl-plan-generate

輸入： 設計工件（來自第三階段）+ 範圍界定工件（來自第一階段）

處理流程：

1. 根據複雜度/單元數/工作量自動選擇層級；如有歧義則提示
   • 快速： 低複雜度，1-3 個單元，<5 小時
   • 標準： 中複雜度，4-8 個單元，5-20 小時
   • 深入： 高複雜度，9 個以上單元，20 小時以上
2. 使用層級專用範本渲染計畫
3. 從範圍界定嵌入排名前 3-5 的高相關性學習經驗
4. 產生唯一檔名：YYYY-MM-DD-NNN-<slug>.md
5. 處理檔名衝突（遞增序號或更新現有檔案）
6. 將計畫儲存至 docs/plans/

輸出： 儲存至檔案的計畫文件，包含：

• 問題與範圍
• 成功標準
• 實作單元（依層級特定詳細程度）
• 風險分析（標準/深入）
• 相關學習經驗（標準/深入）
• 學習缺口（深入）
• 上線備註（標準/深入）

參閱： pwrl-plan-generate/SKILL.md 了解詳細工作流程

規劃層級

層級	最佳適用場景	檔案數	風險	時間
快速	錯誤修正、小調整	1-3	低	5-15 分鐘
標準	大部分功能	4-8	中	30-45 分鐘
深入	架構、安全性、遷移	9 以上	高	1-2 小時

參閱 references/planning-tiers.md 了解完整的層級決策標準與範本範例。

核心原則

• 確定性管道： 階段總是依序執行：範圍界定 → 研究 → 設計 → 產生（無分支、無備援）
• 聚焦決策： 捕捉方法、結構、風險與排序（非程式碼模擬）
• 適中規模： 小型任務 → 簡短計畫；複雜工作 → 更多結構
• 規劃與執行分離： 規劃期間不模擬實作
• 具體明確： 使用具體的檔案、元件與依賴關係
• 保持可攜性： 僅使用儲存庫相對路徑
• 透明工件： 每個階段產出明確的輸出工件供下一階段使用

錯誤處理與復原

理念： 明確失敗，而非默默失敗。每個階段都有清晰的錯誤處理與復原建議。

第一階段（範圍界定）錯誤

• 空白輸入： 提示使用者提供任務描述；重試
• 非軟體領域： 回傳錯誤；建議替代工具
• 模糊輸入： 提出釐清問題；根據使用者回應引導
• 無學習經驗/需求： 繼續進行（非錯誤）

復原： 使用者可以重試、提供釐清或中止

第二階段（研究）錯誤

• 程式碼庫分析失敗： 以最少技術棧資訊繼續
• 識別出高風險領域： 建議外部研究；使用者可以核准或跳過

復原： 使用者可以核准研究、跳過或手動調查

第三階段（設計）錯誤

• 檢測到循環依賴： 報告循環路徑；提示使用者重構
• 單元過多（15 個以上）： 警告複雜度；建議合併
• 資訊不足： 提示新增測試場景或拆分單元

復原： 使用者可以重構、合併或在知情情況下繼續

第四階段（產生）錯誤

• 檔名衝突： 提供選項：更新、遞增或取消
• 層級選擇不明確： 提示使用者選擇層級
• 檔案寫入失敗： 檢查權限/目錄；重試或建議手動儲存

復原： 使用者可以選擇動作或手動儲存

主要輸出

每個計畫包含（依層級而異）：

• 問題與範圍： 清晰的問題框架與預期行為
• 成功標準： 1-3 個特定的完成條件
• 實作單元： 命名 U-ID，附帶依賴關係、檔案、方法與驗收標準
• 相關學習經驗： 連結的學習檔案及其適用性備註（標準/深入）
• 學習缺口： 需要實作後記錄的領域（深入）
• 層級特定章節： 風險分析、替代方案、上線備註（標準/深入）

互動方式

• 使用平台的 ask_user_questions 擴充功能進行所有決策
• 每次只問一個問題
• 盡可能使用多選題
• 若輸入為空白，則詢問：「您想要規劃什麼？請描述任務或專案。」
• 發生錯誤時提供清晰的復原建議

架構：無代理路由

與先前版本的差異：

之前： 技能偵測代理是否可用，然後委派給代理或執行單體備援（兩個程式碼路徑）

之後： 技能直接依序呼叫微技能——單一確定性管道，無分支：

pwrl-plan 編排器
├── 1. 呼叫 pwrl-plan-scope → 取得範圍界定工件
├── 2. 呼叫 pwrl-plan-research → 取得研究工件
├── 3. 呼叫 pwrl-plan-design → 取得設計工件
└── 4. 呼叫 pwrl-plan-generate → 儲存計畫檔案

優點：

• ✅ 更容易理解（單一程式碼路徑）
• ✅ 更容易測試（無分支邏輯）
• ✅ 更易於維護（微技能可獨立測試）
• ✅ 更具組合性（微技能可重複用於其他工作流程）
• ✅ 更好的錯誤處理（每個階段明確）

微技能參考

• pwrl-plan-scope — 脈絡與範圍收集
• pwrl-plan-research — 模式發現與風險識別
• pwrl-plan-design — 單元分解與依賴繪製
• pwrl-plan-generate — 計畫渲染與檔案產生

相關文件

• references/planning-tiers.md — 層級定義與決策標準
• docs/guides/micro-skill-patterns.md — 如何以新微技能進行擴展
• docs/guides/skill-architecture-refactoring.md — 重構的理論基礎

測試與驗證

全面的測試覆蓋率：

• pwrl-plan-scope（U1.1）超過 30 個測試
• pwrl-plan-research（U1.2）超過 25 個測試
• pwrl-plan-design（U1.3）超過 35 個測試
• pwrl-plan-generate（U1.4）超過 30 個測試
• 完整編排管道的整合測試超過 30 個

向後相容性：

• 與先前版本相同的輸入/輸出行為
• 現有計畫成功產生
• 對使用者無重大變更

常見問題

問：如果某個階段失敗了，我可以跳過或重試嗎？

答：可以。每個階段都有明確的錯誤處理與復原建議。您可以重試、提供釐清、修改範圍或中止。不會發生無聲失敗。

問：我可以只使用單一微技能嗎？（例如只從設計階段產生計畫）

答：編排器預期依序呼叫所有四個階段。如果您想使用單一微技能，請直接按名稱呼叫：/pwrl-plan-scope、/pwrl-plan-design 等。

問：為什麼沒有代理路由？

答：代理在沒有增加價值的情況下增加了複雜度。微技能管道是確定性的、可測試的且更容易理解。直接技能呼叫更簡單且更易於維護。

問：我可以為其他工作流程擴展這個框架嗎？

答：可以！微技能是可重複使用的。例如，pwrl-work 可以使用 pwrl-plan-design 進行單元分解。請參閱 docs/guides/micro-skill-patterns.md。

---

狀態： 純技能管道（無代理路由） 版本： 2.0（從依賴代理的架構重構而來） 建立日期： 2026-06-11