---
name: plan
description: 將模糊需求煉成可執行計畫並立即執行。僅由 `/plan {需求}` 顯式觸發。流程：呼叫 `ask_user` tool 依需求複雜度蒐集多面向資訊（核心 3 維度為底，依風險／不可逆性／資源缺口擴充至 5-7 題）→ 呼叫 `generate_plan` tool 產出結構化計畫 → 視計畫缺口 ask_user 補問 或 直接逐步執行。第一個 tool call 永遠是 `ask_user`；不自己組計畫，必走 `generate_plan` tool。
---

# Plan — 需求煉計畫並執行

## 你的執行流程

```
收到 /plan
  ↓
呼叫 ask_user (蒐集第一面向：方向)
  ↓
依回答呼叫 ask_user (依需求複雜度逐題追問，3-7 題不等)
  ↓
判斷資訊是否足夠 generate_plan
  ├─ 不足 → 繼續 ask_user
  └─ 足夠 → 呼叫 generate_plan tool (傳入完整需求 + context)
  ↓
讀取計畫輸出
  ↓
若計畫有缺口 (未知參數 / 模糊驗收 / 多種路徑可選) → 呼叫 ask_user 補問
若計畫完整 → 判斷產出性質：
  ├─ 執行類 (操作 / 變更 / 部署) → 逐步執行並回報
  └─ 結果類 (分析 / 報告 / 文件) → 存檔成 .md 並用附件傳送
  ↓
全部完成輸出總結
```

每個箭頭都是「直接做下一步」。任何「等使用者文字回覆才繼續」的暫停 = 流程錯誤。**禁止自己組計畫文本，計畫必須來自 `generate_plan` tool 的回傳結果。**

## 步驟 1：蒐集需求（呼叫 ask_user）

收到 `/plan ...` 後，**你的下一個 action 必須是這個 tool call**：

```json
{
  "tool": "ask_user",
  "arguments": {
    "questions": [
      {
        "question": "你 /plan 後寫的是「{使用者原文}」— 我先對齊方向：你要的具體是哪一塊？",
        "options": ["{依需求類型給 3-4 個方向選項}", "..."]
      }
    ]
  }
}
```

**範例（投資／股票類需求）**：

```json
{
  "tool": "ask_user",
  "arguments": {
    "questions": [
      {
        "question": "你說「tsmc 分析」— 我先對齊角度：你要的是哪一塊？",
        "options": [
          "短線進出點位（幾天到幾週）",
          "中長線分批策略（數月到一年）",
          "估值合理性 / 基本面",
          "與其他標的比較"
        ]
      }
    ]
  }
}
```

**範例（程式／工程類需求）**：

```json
{
  "tool": "ask_user",
  "arguments": {
    "questions": [
      {
        "question": "你說「重構 X 模組」— 我先對齊目標：主要動機是哪一個？",
        "options": [
          "效能優化",
          "可讀性 / 維護性",
          "支援新功能",
          "修 bug / 技術債"
        ]
      }
    ]
  }
}
```

收到使用者選擇後，**依答案動態決定下一題**（同樣是 `ask_user` tool call）。提問題數**不固定**——簡單需求 3 題即可，複雜／高風險／不可逆需求應拉到 5-7 題，直到累積資訊足以讓 `generate_plan` 產出無 `{未填}` 的計畫為止。

**面向清單（依需求性質取用，非全題必問）：**

| 類別 | 面向 | 何時必問 |
|---|---|---|
| **核心（建議全問）** | 方向／角度 | 一律問（步驟 1 第一題） |
| | 要做到什麼（具體交付物） | 一律問 |
| | 成功怎麼判斷（驗收標準） | 一律問 |
| **範圍** | 邊界（哪些算 in-scope、哪些 out-of-scope） | 需求模糊或牽涉多模組時 |
| | 時間／時程限制 | 含「快」「急」「截止日」字樣，或會影響選擇方案時 |
| **資源／環境** | 已知資源（資料源、API key、預算） | 計畫會用到外部資源時 |
| | 技術棧／執行環境偏好 | 跨多語言／多平台可選時 |
| **風險／約束** | 禁止操作（不可動的檔案／系統／資料） | 涉及生產環境、共用資源、第三方系統時 |
| | 不可逆動作的處理（push／發佈／下單／刪除） | 計畫含上述任一時必問 |
| | 風險容忍度（要保守還是激進） | 投資／策略類需求 |
| **後備** | 失敗時的 fallback | 不可逆步驟、或步驟有相依時 |

**停止提問的判準：**

- 累積資訊足以讓 `generate_plan` 產出**每一步都有明確驗收、無 `{未填}`、無分支待決**的計畫
- 再問下去只會得到「我不知道，你決定」這類無資訊回答
- 達到上述任一條件就進步驟 2，不要硬湊題數

**對照表：寫成這樣 → 改成這樣**

| 你想寫的文字 | 應該改成的 tool call |
|---|---|
| 「我先確認方向：你要的是哪一塊？回我就繼續」 | 呼叫 `ask_user` |
| 「需求是什麼：X、要做到什麼：Y、結果要什麼：Z。對嗎？」（自己填多面向請使用者確認） | 呼叫 `ask_user` 主動問每個面向，不是事後請確認推測 |
| 問完 3 題就停（即使資訊明顯不足以規劃） | 繼續呼叫 `ask_user` 補問，直到資訊足夠 generate_plan |
| 「下一步如果你要我繼續，我會...」 | 直接做下一步（蒐集完就輸出計畫，計畫完就執行） |
| 「這不是 `/plan` 指令，所以我不走規劃技能流程」 | 使用者輸入以 `/plan` 開頭就是 `/plan` 指令，走流程 |

## 步驟 2：呼叫 generate_plan tool

步驟 1 蒐集到的資訊足以產出無 `{未填}` 計畫時，**同一輪直接呼叫 `generate_plan` tool**，不要問「要不要開始規劃」，也不要自己寫計畫。

```json
{
  "tool": "generate_plan",
  "arguments": {
    "requirement": "{彙整使用者原始 /plan 文本 + ask_user 各輪回答，逐維度敘述}",
    "context": "{執行環境 / 已知資源 / 限制 / 禁止操作；無則留空}"
  }
}
```

**requirement 撰寫要點：**

- 含使用者原始 `/plan` 後接文本
- 含**所有**已蒐集面向的回答（不限於核心 3 題；若有問範圍／資源／風險／後備也要併入）
- 用敘述句串接，不省略 ask_user 答覆

**context 撰寫要點（無則留空字串）：**

- 當前對話已知的環境（OS／可用工具／資料來源）
- 使用者明示的禁止操作
- 不可逆性提示（會動到帳戶／真實交易／生產環境）

收到 tool 回傳的計畫 markdown 後進入步驟 3。

## 步驟 3：依計畫狀態分流（補問 or 執行）

讀完 `generate_plan` 回傳的計畫，判斷是否有以下缺口：

| 缺口類型 | 行為 |
|---|---|
| 計畫含 `{未填}`／`<TBD>`／「需確認」字樣 | 呼叫 `ask_user` 補問該欄 |
| 多個步驟有相互衝突的前置條件 | 呼叫 `ask_user` 釐清優先順序 |
| 不可逆步驟（含「刪除」「push」「發佈」「下單」）動作描述含糊 | 呼叫 `ask_user` 確認動作細節 |
| 計畫每步驟驗收明確、無未填、無衝突 | **直接執行第一步**（步驟 4） |

補問用 `ask_user` tool（與步驟 1 同模式），收到回答後**重新呼叫 `generate_plan` 並把答案併入 `context`**，再次回到步驟 3 判斷。

## 步驟 4：立刻執行（不問權限）

計畫無缺口後，**同一輪緊接著開始執行第一個步驟**。不要問「要不要執行」、不要等使用者說「開始」。使用者執行 `/plan` 就是要規劃並執行，無須中間確認。

**先判斷產出性質，二選一**：

| 性質 | 判準 | 走法 |
|---|---|---|
| **執行類** | 計畫步驟主要為操作／變更／部署／呼叫外部系統 | 4a 逐步執行並回報 |
| **結果類** | 計畫產出為分析／報告／策略／研究／文件本身 | 4b 存檔成 `.md` 用附件傳送 |

混合型（先研究後執行）以「最終交付物」決定；交付物是文件→走 4b。

### 4a. 執行類：逐步執行並回報

逐步執行，每步輸出回報：

```
[Step 1/N] {Step Title}
  動作: {what you did}
  產出: {observed result}
  驗收: ✅ {passed} / ❌ {failed + reason}
→ 進入 Step 2
```

執行規則：

- 一般步驟直接做，不需逐步問權限
- **僅不可逆操作**（刪檔 / push / 發佈 / 下單 / 寫到外部系統）前呼 `ask_user` 二次確認
- 任一步驟驗收失敗 → 停下，呼叫 `ask_user`：「重試 / 跳過 / 修改計畫 / 中止」四選一
- 全部完成 → 輸出總結（執行步數、產出清單、未達成項）

### 4b. 結果類：存檔 + 附件傳送

結果類產出**一律存成 `.md` 檔案**並以附件傳送，避免長文塞爆後續歷史訊息。

**步驟**：

1. **寫檔**：完整結果（含分析過程、數據、結論、附錄）寫到絕對路徑

   ```
   ~/.config/agenvoy/download/plan-{slug}-{YYYYMMDD-HHmm}.md
   ```

   - `{slug}`：取需求關鍵字 kebab-case（例：`tsmc-mid-term`／`auth-refactor-design`）
   - `{YYYYMMDD-HHmm}`：當前時間（從 user message 開頭 `當前時間: ...` 取）

2. **對話只回摘要**：5-10 行內，涵蓋
   - 核心結論（1-2 行）
   - 關鍵數據／路徑／決策（3-5 行）
   - 風險／限制（1-2 行）

3. **末尾整行附 marker**（必為訊息最後一行，不可中間夾雜）：

   ```
   [SEND_FILE:/Users/pardn/.config/agenvoy/download/plan-tsmc-mid-term-20260521-1430.md]
   ```

**範例輸出**：

```
TSMC 中長線分批策略分析完成。

核心結論：當前 925 元偏估值上緣，建議分 3 批進場（920 / 880 / 820）。
關鍵假設：2026 EPS 56-58、本益比 16-18x、台幣匯率 31-32。
主要風險：地緣政治、Apple 訂單能見度、Intel 競爭。
建議部位上限：總資金 15%。

完整分析（含估值模型、敏感度、技術面、籌碼面）見附件。

[SEND_FILE:/Users/pardn/.config/agenvoy/download/plan-tsmc-mid-term-20260521-1430.md]
```

**禁忌**：

- ❌ 把完整分析貼進對話正文（歷史訊息會爆量、後續 LLM call token 線性上升）
- ❌ marker 寫成 ` `FILE: <path>` ` 或夾在段落中間（解析器只認最後行整行 `[SEND_FILE:...]` 或獨立行 `^FILE: <path>$`）
- ❌ 檔名省略時間戳（同一 slug 多次規劃會覆蓋）
- ❌ 寫到 `/tmp`／`~/Downloads`／工作目錄（必固定 `~/.config/agenvoy/download/`）

## 常見錯誤對照

| 觀察到的錯誤行為 | 為什麼錯 | 正確做法 |
|---|---|---|
| 用文字「請問...？」提問後等使用者文字回覆 | `ask_user` 是 tool 不是文字 chat；文字回覆無法觸發 skill 的多輪結構 | 呼叫 `ask_user` tool（有 `questions`/`options` 參數的 JSON） |
| 從 `/plan` 後接文本推測各面向，列出來請使用者確認 | 推測等於假設使用者意圖，計畫會對不上 | 主動 `ask_user` 逐題問 |
| 不論需求複雜度都只問 3 題就送 `generate_plan` | 高風險／不可逆需求資訊不足會產出含 `{未填}` 的計畫 | 依面向清單依需求性質追問至 5-7 題 |
| 「這不是 /plan 指令」「下次用 /plan」這類拒絕走流程 | 使用者已用 `/plan` 觸發，就是要走規劃流程 | 走流程，不繞道 |
| 自己組計畫文本，不呼 `generate_plan` tool | 自寫計畫格式漂移、缺結構化欄位、跳過 planning subagent 的推理 | 必呼 `generate_plan`，傳完整 requirement + context |
| 收到 `generate_plan` 結果就立刻執行，不檢查缺口 | 計畫可能有 `{未填}` 或衝突，照跑會出錯 | 先依步驟 3 判斷缺口，必要時 ask_user 補問再 regenerate |
| 補問完直接執行，不重新呼叫 `generate_plan` | 計畫沒更新就照舊計畫跑，補問白費 | 補問結果併入 context，重新 `generate_plan` 再判斷 |
| 蒐集完問「要不要規劃」 | 使用者執行 `/plan` 就是要規劃，不需中間確認 | 直接呼 `generate_plan` |
| 規劃完問「要不要執行」 | 使用者執行 `/plan` 就是要執行，不需中間確認 | 直接開始執行第一步 |
| 執行階段每步驟前問 `ask_user` | 計畫已產出，逐步授權不需要 | 直接做；只有不可逆步驟才二次確認 |
| 結果類（分析／報告）把完整內容貼進對話 | 長文進歷史會讓後續 LLM call token 線性爆量 | 寫到 `~/.config/agenvoy/download/plan-{slug}-{ts}.md`，對話只回摘要 + 末行 `[SEND_FILE:...]` |
| 結果類存檔但 marker 寫中間段落 | 解析器只取末行整行 marker | 摘要寫完，最後**獨立一行**放 `[SEND_FILE:<絕對路徑>]` |
