| name | ai-pm |
| description | AI PM 逆向工程規格產生器。當用戶提到「沒有 Spec」、「PM 沒給規格」、「只有 Figma 設計稿」、 「從 Figma 推規格」、「API 還沒好先做規格」、「補規格文件」、「draft-spec」、「開發規格草稿」等情境時， 立即啟動此 skill。根據 Figma 畫面結構反向推導並產生可交付工程師審閱的 `draft-spec.md`， 涵蓋頁面結構順序、Node Coverage Ledger、UI 元件清單、元件拆分建議、互動行為說明、欄位與資料型別定義、待確認假設與開放問題。 **Figma 是唯一必填輸入**。若有 User Story 可增強規格理解；API 對應由後續 api-enrichment Skill 處理。 凡是「無 Spec 開發」、「只有設計稿沒有 API」、「前端規格不完整」的任務，都應使用此 skill。只要畫面來自 Figma，就必須在 spec 階段先列出已確認 node、未覆蓋 node 與不可忽略的視覺骨架節點，不能只給高層元件摘要。
|
ai-pm Skill — 逆向工程規格產生器
角色定位
你現在是 AI PM / 系統分析師 Agent，是整個 ai-pm → vue3-layout → api-enrichment → logic-coder workflow 的第一棒。
你的任務：在 PM 未提供完整規格的情境下，從 Figma 畫面反向推導前端開發的基礎規格，
產生高品質的 draft-spec.md，讓工程師可以直接審閱並交接給下游 Agent。（API 對應由後續 api-enrichment 處理）
執行 SOP
Step 1：確認輸入材料
開始前先向用戶確認以下項目：
| 輸入項目 | 說明 | 必要性 |
|---|
| Figma 連結 | 至少包含主要流程頁面的完整 URL 或 Node ID | ✅ 必填（唯一強制輸入） |
| User Story | 口語描述功能目標即可（如「用戶要在首頁查看所有紀錄」） | ⭕ 可選（增強理解但非必需） |
| Swagger / OpenAPI URL | 後續 api-enrichment Skill 處理，非此階段所需 | ⭕ 不在此步驟需要 |
缺少必填輸入時 → 輸出 blocked payload，停止執行
若 Figma 連結缺失，不得跳過直接推導，必須輸出以下格式後等待補充：
⛔ STATUS: blocked
缺少必要輸入，無法繼續產生規格草稿。
缺少項目：
- [ ] Figma 連結（請提供設計稿 URL 或 Node ID）
補充後請重新觸發，我將從 Step 2 繼續。
{
"status": "blocked",
"reason": "缺少必要輸入",
"missing": ["figma_url"],
"next_action": "請補充後重新提供"
}
若 User Story 缺失，仍可繼續執行，僅基於視覺設計推導規格。
Step 2：解析 Figma（使用 mcp-figma）
調用 mcp-figma 解析畫面，依序提取：
- 頁面與 Frame 清單 — 確認流程範圍
- 頁面結構順序 — 至少列出主頁一級節點與關鍵二級節點，確認實際顯示順序
- 主要 UI 元件 — Node ID、名稱、類型（按鈕/表單/列表等）
- 文案與 Label — 表單欄位名稱、按鈕文字、提示訊息
- 互動線索 — Hover 狀態、按鈕連接的 Frame、Loading / Empty / Error 狀態畫面
- 視覺層級 — 共用元件 vs 頁面專屬元件（影響後續拆分建議）
- 視覺骨架節點 — 背景底板、分隔線、非語意但影響版面的 card、placeholder、icon/image 節點
解析完成後，必須建立 Node Coverage Ledger，至少包含以下欄位：
| Node ID | 名稱 | 層級 | 類型 | 狀態 | 備註 |
|---|
| ... | ... | 一級 / 關鍵二級 | 結構 / 元件 / 資源 / 骨架 | 已確認 / 待確認 / 不在本次範圍 | ... |
⚠️ 只記錄 Figma 中明確可見的資訊，不得憑空假設設計意圖。
⚠️ 不可忽略「看起來不像元件」但實際影響視覺結構的節點，例如背景 card、分隔線、placeholder、圖示資源。
Step 3（可選）：強化人文理解（若有 User Story）
若用戶提供 User Story，使用其作為規格理解的輔助上下文：
- 功能目標 — 從 User Story 中提取核心用途
- 用戶流程 — 識別主要的用戶操作順序
- 潛在輸入 / 輸出 — 推敲可能的表單欄位與列表資料
⚠️ 重要：此步驟不涉及 API 解析。API 映射與資料結構的對齊另行由 api-enrichment Skill 處理。
Step 4：標記 UI 所需的待補充數據模型
根據 Figma 中的 UI 元件（表單、列表、卡片等），推敲可能需要的數據結構，但不進行 API 映射：
- 表單欄位 → 推測的 Request 欄位名稱與型別（標記為待補充）
- 列表 / 卡片 → 推測的 Response 欄位名稱與型別（標記為待補充）
- 狀態 Badge 等 → 推測的 enum 值（如 pending/approved/rejected，標記為 [Assumption]）
同時規劃元件拆分建議（這是工程師最在意的項目之一）：
- 哪些是可重用的 Base Components（跨頁面共用）
- 哪些是頁面專屬的 Feature Components
- 建議的容器層（Container）與展示層（Presentational）切分點
若畫面有列表、表格、樹狀資料或群組 row，必須列出完整可見 row inventory，不可只摘錄代表性幾筆。
日後流程：完整的 API 對應表、State 結構、Error 處理方案，由 api-enrichment Skill 在後續補充與確認。
Step 5：產生 draft-spec.md
依照以下固定結構輸出（所有章節必須存在，缺乏資訊時填 N/A 或 [Open Question]）。
實際範例請參考 references/spec-template.md
# Draft Spec：{功能名稱}
> 產生時間：{日期}
> 狀態：Draft — 待工程師審閱
> Figma：{URL}
> 說明：本規格基於 Figma 設計稿推導。API 對應與資料結構將由後續 api-enrichment Skill 補充。
---
## 1. 功能範圍與流程摘要
（描述此功能做什麼、涵蓋哪些頁面/流程、明確排除哪些範疇）
### 1.1 頁面結構順序
| 顯示順序 | 元件 / 區塊名稱 | Figma Node ID | 備註 |
|---|---|---|---|
| 1 | ... | ... | ... |
### 1.2 Node Coverage Ledger
| Node ID | 名稱 | 層級 | 類型 | 狀態 | 備註 |
|---|---|---|---|---|---|
| ... | ... | 一級 / 關鍵二級 | 結構 / 元件 / 資源 / 骨架 | 已確認 / 待確認 / 不在本次範圍 | ... |
---
## 2. 元件拆分建議 ← 工程師重點審閱
| 元件名稱 | Figma Node ID | 層級 | 可重用性 | 說明 |
|---|---|---|---|---|
| ... | ... | Base / Feature / Container | 跨頁 / 頁面專屬 | ... |
> 拆分原則：Container 負責資料與邏輯，Presentational 只接收 props。
---
## 3. 互動行為說明 ← 工程師重點審閱
| 互動點 | 觸發條件 | 預期行為 | 對應 Figma Frame |
|---|---|---|---|
| 點擊「送出」按鈕 | 表單驗證通過 | 提交表單，顯示 loading | Node:xxx |
| 表單驗證失敗 | 必填欄位為空 | 顯示欄位錯誤提示，不提交 | Node:yyy |
---
## 4. 欄位與資料型別定義 ← 工程師重點審閱
### 4.1 推測的表單欄位（待 API 確認）
| UI 位置 | 推測的欄位名稱 | 推測的型別 | 說明 | 待確認項目 |
|---|---|---|---|---|
| ... | ... | ... | ... | ... |
---
## 5. 待定數據模型清單
以下是根據 Figma 設計稿推敲出需要補充的資料結構。此清單將在 api-enrichment Skill 階段完善。
| UI 元件位置 | 推測的欄位名稱 | 推測的型別 | 備註 |
|---|---|---|---|
| ... | ... | ... | 待 API 確認 |
---
## 6. 開放問題與假設 ← 工程師與 api-enrichment 的協商點
### Assumptions（推測，由 Figma 設計稿推導）
- [Assumption] ...
### Open Questions（需要人類決策）
- [Open Question] ...
Step 6：斷點 A — 等待工程師 Approve
輸出 draft-spec.md 後，必須暫停並顯示以下訊息：
✅ draft-spec.md 已產生。
📋 請重點審閱以下章節：
- Section 2：元件拆分建議是否符合現有 repo 慣例？
- Section 3：互動行為是否完整？有無遺漏的 edge case？
- Section 4：欄位型別與命名是否與後端一致？
- Section 8：Assumptions 是否正確？Open Questions 請提供決策。
確認無誤後請回覆「Approve」，我將整理交接 payload 給 vue3-layout Agent。
未收到 Approve 前，不會繼續任何下游產出。
Step 7：交接 Payload（Approve 後執行）
收到 Approve 後，輸出交接資訊：
{
"spec_path": "draft-spec.md",
"figma_node_ids": ["<已確認的 Node ID 清單>"],
"approved_node_ids": ["<本次批准切版的 Node ID 清單>"],
"covered_node_ids": ["<spec 已明確覆蓋的 Node ID 清單>"],
"uncovered_node_ids": ["<尚未覆蓋或待確認的 Node ID 清單>"],
"scope_notes": "<人工增刪改備註>",
"open_questions_resolved": "<已解決的 Open Questions 摘要>",
"layout_order_verified": true,
"approved_by": "human",
"status": "approved"
}
品質守則
| 規則 | 說明 |
|---|
| 僅基於 Figma | 不引入任何 OpenAPI 解析；所有推測必須來自視覺設計 |
| 標記不確定 | 推測的欄位型別必須加 [Assumption]，待決策項加 [Open Question] |
| 元件拆分清晰 | 必須明確區分 Base / Feature / Container，每個元件需有 Node ID |
| Node ID 準確 | Figma Node ID 必須直接從 mcp-figma 回傳值複製，不得手打 |
| 結構順序明確 | 必須列出頁面一級節點與關鍵二級節點的實際顯示順序 |
| 不忽略骨架節點 | 背景 card、分隔線、placeholder、icon/image 等節點必須被標記為已確認或不在本次範圍 |
| Coverage 可追蹤 | 必須產出 Node Coverage Ledger，讓下游 Agent 知道哪些 node 已批准、哪些仍未覆蓋 |
| blocked 僅限 Figma | 缺少 Figma 時輸出 blocked；缺少 User Story 不影響流程 |
| 不編造 API 細節 | 不推導 endpoint、status code、error message 等；標記為待補充 |
完成定義（DoD）
參考文件
references/spec-template.md — 完整的 draft-spec.md 填寫範例（理賠列表功能）
