product-playbook 1.0.0

package/i18n/zh-TW/references/rules-full.md

@@ -0,0 +1,66 @@
+# 📦 完整模式步驟序列（共 20 步 + 最終產出）
+
+> 此檔案為完整模式的權威步驟定義。由 SKILL.md 核心派發載入。
+
+## 步驟序列
+
+```
+Phase 0：前置
+  S1.  機會評估 + DHM → 讀取 references/00-opportunity-check.md
+  S2.  Strategy Blocks + Rumelt 策略內核 → 讀取 references/01-strategy.md
+
+Phase 1：Discovery
+  S3.  Persona Table → 讀取 references/02a-persona.md
+  S4.  Persona 卡片 → 讀取 references/02a-persona.md
+  S5.  JTBD 分析 → 讀取 references/02b-jtbd.md
+  S6.  機會解法樹 OST → 讀取 references/02c-ost-journey.md
+  S7.  User Journey Map → 讀取 references/02c-ost-journey.md
+
+Phase 2：Define
+  S8.  痛點彙整表 → 讀取 references/03-define.md
+  S9.  April Dunford 定位 → 讀取 references/03-define.md
+  S10. HMW 問題轉化 → 讀取 references/03-define.md
+  S11. 機會評估表 → 讀取 references/03-define.md
+
+Phase 3：Develop
+  S12. PR-FAQ → 讀取 references/04a-prfaq.md
+  S13. 平行原型 → 讀取 references/04b-solutions.md
+  S14. Pre-mortem → 讀取 references/04b-solutions.md
+  S15. GEM + RICE 優先排序 → 讀取 references/04b-solutions.md
+  S16. User Story → 讀取 references/04b-solutions.md
+  S17. MVP + Not Doing List → 讀取 references/04c-mvp.md
+
+Phase 4：Deliver
+  S18. North Star + 三層訊號 + Aha Moment → 讀取 references/05a-northstar-aha.md
+  S19. PMF 等級判定 + GTM 策略 + 商業模式 → 讀取 references/05b-pmf-gtm.md
+  S20. 假設驗證計畫 → 讀取 references/05c-validation-spec.md
+────
+最終產出 → 產品規格摘要（references/05c-validation-spec.md → 4.6）+ 最佳切入點分析
+```
+
+> 完整模式中 4.1 Empowered Teams 在產出對象為老闆/跨部門時加入 S18 之前，否則跳過。
+
+## Reference 載入指示
+
+進入各步驟時，僅讀取對應的 reference 檔案（不要預先全部載入）：
+
+| 步驟 | Reference 檔案 |
+|------|---------------|
+| S1 | `references/00-opportunity-check.md` |
+| S2 | `references/01-strategy.md` |
+| S3-S4 | `references/02a-persona.md` |
+| S5 | `references/02b-jtbd.md` |
+| S6-S7 | `references/02c-ost-journey.md` |
+| S8-S11 | `references/03-define.md` |
+| S12 | `references/04a-prfaq.md` |
+| S13-S16 | `references/04b-solutions.md` |
+| S17 | `references/04c-mvp.md` |
+| S18 | `references/05a-northstar-aha.md` |
+| S19 | `references/05b-pmf-gtm.md` |
+| S20 + 最終產出 | `references/05c-validation-spec.md` |
+
+## 最終產出格式
+
+**最佳切入點分析**（完整邏輯鏈）＋ **產品規格摘要**
+
+完成後，依 `references/rules-end-of-flow.md` 執行流程結束規則。

package/i18n/zh-TW/references/rules-import-document.md

@@ -0,0 +1,261 @@
+# 文件匯入解析規則
+
+> 使用者上傳 PDF / DOCX / PPTX 檔案，或觸發 `/parse [file]` 時載入。
+> 首次使用時先載入 `rules-document-tools.md` 確認工具已安裝。
+> 本規則與 `rules-file-integration.md` 搭配使用——該檔定義「何時觸發」，本檔定義「如何解析」。
+
+---
+
+## 解析目標
+
+將任何格式的輸入文件轉換為**結構化 Markdown**，供後續流程使用：
+- Feature Extension / Revision 模式的 S1 情境蒐集
+- 增量更新的原始文件基底
+- 一般性的文件內容提取
+
+---
+
+## PDF 解析：三層策略 + 逐頁檢測
+
+### 總覽
+
+```
+輸入 PDF
+  │
+  ▼
+pymupdf 逐頁文字提取（零成本）
+  │
+  ├── 該頁文字 > 30 字元 → ✅ 直接轉 Markdown（層 1）
+  │
+  └── 該頁文字 ≤ 30 字元（空白 / 向量路徑 / 掃描件）
+        │
+        ├── 預設 → Claude Vision 語意解析（層 2）
+        │
+        └── Vision 不可用 / Token 預算不足 → Tesseract OCR（層 3）
+```
+
+### 步驟 1：逐頁類型檢測
+
+**關鍵原則**：以「頁」為單位檢測，而非整份文件。一份 PDF 可能混合數位文字頁和掃描圖片頁。
+
+```python
+import fitz  # pymupdf
+
+doc = fitz.open(pdf_path)
+total_pages = len(doc)
+page_results = {}
+
+for i in range(total_pages):
+    page = doc[i]
+    text = page.get_text("text").strip()
+
+    if len(text) > 30:
+        # 層 1：數位文字，直接提取
+        page_results[i] = {"type": "digital", "text": text}
+    else:
+        # 需要 Vision 或 OCR
+        page_results[i] = {"type": "needs_vision", "text": None}
+
+digital_count = sum(1 for p in page_results.values() if p["type"] == "digital")
+vision_count = total_pages - digital_count
+
+print(f"PDF 分析：{total_pages} 頁，{digital_count} 頁可直接提取，{vision_count} 頁需視覺解析")
+```
+
+### 步驟 2：大文件處理策略
+
+| 條件 | 策略 |
+|------|------|
+| 全部頁面為 digital（vision_count = 0）| 直接提取所有頁面，零成本 |
+| vision_count ≤ 20 | 一次用 Claude Vision 讀取所有需視覺解析的頁面 |
+| vision_count > 20 | 分批處理（每批 ≤ 20 頁），合併結果 |
+| 總頁數 > 50 且 vision_count > 20 | 詢問使用者是否全文解析或指定頁面範圍 |
+
+**大文件（>50 頁）的使用者確認提示**：
+
+```
+📄 此 PDF 共 {total_pages} 頁：
+  • {digital_count} 頁可直接提取文字（免費）
+  • {vision_count} 頁需要視覺解析（消耗 Vision Token）
+
+請選擇：
+  1️⃣ 全文解析（完整但消耗較多 Token）
+  2️⃣ 只解析特定頁面（請輸入頁碼範圍，如 1-10,15,20-25）
+  3️⃣ 只提取可直接提取的頁面（跳過掃描/向量頁面）
+```
+
+### 步驟 3：層 1 — pymupdf 直接提取
+
+```python
+def extract_digital_pages(doc, page_results):
+    """提取所有數位文字頁面"""
+    markdown_parts = []
+    for i, result in sorted(page_results.items()):
+        if result["type"] == "digital":
+            markdown_parts.append(f"<!-- Page {i+1} -->\n{result['text']}")
+    return "\n\n".join(markdown_parts)
+```
+
+### 步驟 4：層 2 — Claude Vision 語意解析
+
+對於 `needs_vision` 類型的頁面，先用 pymupdf 渲染為 PNG 圖片，再用 Claude 的 Read 工具讀取。
+
+**渲染為圖片**：
+```python
+def render_pages_to_png(doc, page_indices, dpi=300):
+    """將指定頁面渲染為 PNG"""
+    output_files = []
+    for i in page_indices:
+        page = doc[i]
+        pix = page.get_pixmap(dpi=dpi)
+        output_path = f"/tmp/pdf-page-{i+1:04d}.png"
+        pix.save(output_path)
+        output_files.append((i, output_path))
+    return output_files
+```
+
+**Claude Vision 解析 Prompt**：
+
+對每個需要視覺解析的頁面（或批次），使用 Read 工具讀取 PNG 後，依以下 prompt 轉換：
+
+```
+你正在閱讀一份 PDF 文件的第 {page_num}/{total_pages} 頁。
+請將此頁面的內容精確轉換為 Markdown 格式。
+
+嚴格規則：
+1. 表格 → Markdown table（保留所有欄位、行數、對齊方式）
+2. 標題 → # / ## / ### 對應原始層級
+3. 編號清單 → 1. 2. 3.（保留原始編號）
+4. 項目符號 → - 或 •
+5. 粗體/斜體 → **粗體** / *斜體*
+6. 圖表/圖片 → > [圖表：簡述內容]
+7. 頁首、頁尾、頁碼 → 忽略
+8. 數字、日期、人名、帳號 → 必須 100% 精確，不得猜測
+9. 不要添加原文沒有的內容
+10. 不要翻譯——保留原文語言
+```
+
+> **為什麼這比 OCR 強**：Claude 理解表格的「語意結構」（第一行是表頭、哪些欄位對齊），而 Tesseract 只能逐字元辨識後用規則重建表格，經常失敗。
+
+### 步驟 5：層 3 — Tesseract OCR Fallback
+
+僅在以下情況使用：
+- 使用者明確要求節省 Token
+- Claude Vision 不可用（API 限制等）
+- 離線環境
+
+```python
+import subprocess
+from PIL import Image
+
+def ocr_page(png_path, lang="chi_tra+eng"):
+    """Tesseract OCR 單頁"""
+    # macOS 的 tesseract 可能無法直接讀取 PNG，需先轉 TIFF 或用 stdin
+    tiff_path = png_path.replace('.png', '.tiff')
+    Image.open(png_path).save(tiff_path)
+
+    result = subprocess.run(
+        ['tesseract', 'stdin', 'stdout', '-l', lang],
+        stdin=open(tiff_path, 'rb'),
+        capture_output=True, text=True, timeout=120
+    )
+    return result.stdout
+```
+
+**Tesseract 注意事項（實戰經驗）**：
+- macOS 上 tesseract 可能無法直接讀取 PNG 檔案，需用 `stdin` 管道或先轉 TIFF
+- 建議解析度 300dpi
+- `chi_tra+eng` 語言包同時辨識繁體中文和英文
+- OCR 結果需後處理：合併斷行、修復表格結構
+
+### 步驟 6：合併所有頁面
+
+```python
+def merge_all_pages(digital_md, vision_md_list):
+    """按頁序合併所有頁面的 Markdown"""
+    all_pages = {}
+    # digital pages
+    for page_num, md in digital_md.items():
+        all_pages[page_num] = md
+    # vision/ocr pages
+    for page_num, md in vision_md_list.items():
+        all_pages[page_num] = md
+
+    # 按頁碼排序，合併
+    final_md = []
+    for i in sorted(all_pages.keys()):
+        final_md.append(all_pages[i])
+
+    return "\n\n---\n\n".join(final_md)
+```
+
+### 步驟 7：輸出並告知使用者
+
+```
+📄 PDF 解析完成：
+  • 總頁數：{total_pages}
+  • 直接提取：{digital_count} 頁（pymupdf）
+  • 視覺解析：{vision_count} 頁（Claude Vision）
+  • 輸出：{output_path}（Markdown，{字數} 字）
+```
+
+---
+
+## DOCX 解析
+
+```bash
+pandoc "{input_path}" -t markdown -o "/tmp/parsed-{timestamp}.md" --wrap=none
+```
+
+**後處理**：
+- 移除 Pandoc 產生的多餘空行
+- 確認表格格式正確
+
+---
+
+## PPTX 解析
+
+```bash
+pandoc "{input_path}" -t markdown -o "/tmp/parsed-{timestamp}.md" --wrap=none
+```
+
+> Pandoc 會將每張投影片轉為一個 `##` 標題區段。
+
+---
+
+## HTML 解析
+
+```bash
+pandoc "{input_path}" -f html -t markdown -o "/tmp/parsed-{timestamp}.md" --wrap=none
+```
+
+---
+
+## 圖片解析
+
+直接使用 Claude Read 工具讀取圖片，然後依照 Vision 解析 Prompt 轉換為 Markdown。
+
+---
+
+## 與 rules-file-integration.md 的協作
+
+當 `rules-file-integration.md` 偵測到以下場景時，載入本規則：
+
+| 場景 | 動作 |
+|------|------|
+| 使用者在 Feature Extension S1 上傳 PDF | 載入本規則 → 解析 PDF → 提取既有系統背景 |
+| 使用者在 Revision S1 上傳舊版 PRD | 載入本規則 → 解析 PDF → 作為改版基底 |
+| 使用者用 `/parse` 指令 | 載入本規則 → 解析指定檔案 → 輸出 Markdown |
+| 使用者上傳市場報告 PDF | 載入本規則 → 提取關鍵資訊 → 整合到對應步驟 |
+
+### 原始文件識別
+
+解析完成後，若判斷該檔案是「原始文件」（PRD、規格書等），自動標記：
+
+```
+📎 偵測到原始文件——最終產出將基於此檔案進行增量更新。
+  文件結構：{章節數} 個章節，{表格數} 個表格
+  格式慣例：[識別到的格式特徵]
+```
+
+並將文件結構記錄，供 `rules-export-document.md` 在最終產出時使用。

package/i18n/zh-TW/references/rules-product-type.md

@@ -0,0 +1,14 @@
+# 🏢 B2B / B2C 差異化調整
+
+> 確認產品類型後載入此檔案。Claude 自動在各框架中套用以下調整。
+
+| 框架 | B2C 調整 | B2B 調整 |
+|------|---------|---------|
+| **Persona** | 以個人動機/習慣分群 | 區分「購買決策者」和「實際使用者」兩類 Persona；加入「組織規模」「採購流程」欄位 |
+| **JTBD** | 聚焦個人情感性和社交性工作 | 加入「組織層級工作」：幫公司達成什麼目標？個人在組織中完成什麼工作？ |
+| **PMF 判斷** | 以 DAU/MAU、留存率、Sean Ellis Score 為主 | 以「付費客戶數 + 擴展率 + NPS」為主；Level 1 = 3-5 個付費客戶 |
+| **Aha Moment** | 首次使用中體驗到核心價值 | 可能在 Onboarding/試用期才出現；需設計「Time-to-Value」指標 |
+| **MVP** | 可以是一個完整的輕量產品 | 可能需要是一個 Pilot（針對特定客戶的客製化部署） |
+| **GTM** | 以產品驅動增長（PLG）或社群為主 | 以銷售驅動或合作夥伴渠道為主 |
+| **定價** | Freemium / Subscription / 按用量 | 年度合約 / 按座位 / 按用量 / 客製報價 |
+| **North Star** | 用戶活躍度或核心動作完成次數 | ARR、Net Revenue Retention、Active Accounts |

package/i18n/zh-TW/references/rules-progress.md

@@ -0,0 +1,60 @@
+# 🔁 進度持久化與中斷恢復
+
+> 使用者說「暫停」「存檔」或 skill 啟動時檢查進度時載入。
+
+## 進度檔案格式
+
+每完成一個步驟，在專案目錄下建立或更新 `.product-playbook-progress.md`：
+
+```
+# Product Playbook 進度存檔
+
+- 模式：[快速模式 / 完整模式 / ...]
+- 產品類型：[B2C / B2B / ...]
+- 產品描述：[使用者的產品描述]
+- 當前進度：S[X] / S[Y]
+- 最後更新：[時間戳]
+
+## 已完成步驟
+
+### S1：[步驟名稱] ✅
+[該步驟的核心產出，保留足夠細節以便恢復時不需要重做]
+
+### S2：[步驟名稱] ✅
+[同上]
+
+## 待執行步驟
+- S3：[步驟名稱]
+- S4：[步驟名稱]
+- ...
+```
+
+### 功能擴充模式範例
+```markdown
+模式：功能擴充
+步驟：S2/S4
+S1：問題 + 現有系統情境 ✅
+S2：三個平行解法 + AI 推薦 ▶️
+S3：風險評估 ⬜
+S4：執行範圍 ⬜
+```
+
+## 觸發規則
+
+1. **自動儲存**：每個步驟完成並獲得使用者確認後，立即更新進度檔案
+2. **啟動時檢查**：skill 觸發時，先檢查是否存在 `.product-playbook-progress.md`。若存在，顯示：
+```
+偵測到未完成的產品規劃進度（[模式名稱]，S[X]/S[Y]）：
+  1️⃣ 繼續 — 從 S[X] 接續
+  2️⃣ 重新開始 — 清除舊進度，重頭來過
+（輸入 1 或 2）
+```
+3. **暫停指令**：使用者說「暫停」「先做別的」「存檔」時，確認進度檔案已更新，回覆：「進度已存檔至 .product-playbook-progress.md（S[X]/S[Y]）。下次在此專案啟動 skill 時會自動偵測。」
+4. **完成時清理**：流程全部完成並產出最終文件後，詢問使用者是否刪除進度檔案
+6. **版控提醒**：首次建立 `.product-playbook-progress.md` 時，提醒使用者：「⚠️ 建議將 `.product-playbook-progress.md` 加入 `.gitignore`，此檔案可能包含敏感的產品策略資訊。」
+5. **中斷存檔**：當流程進行中偵測到無關 prompt 時（見 SKILL.md 流程中斷處理規則），即使當前步驟尚未完成，也必須存檔。存檔格式在當前步驟標記為 `🔶`（進行中）而非 `✅`，並保存已產出的部分內容：
+```
+### S[X]：[步驟名稱] 🔶（進行中，部分完成）
+[已產出的部分內容]
+⚠️ 此步驟尚未完成，恢復時需從此處繼續
+```

package/i18n/zh-TW/references/rules-quick.md

@@ -0,0 +1,29 @@
+# 🚀 快速模式步驟序列（共 3 步 + 最終產出）
+
+> 此檔案為快速模式的權威步驟定義。由 SKILL.md 核心派發載入。
+
+## 步驟序列
+
+```
+S1. JTBD 陳述 → 讀取 references/02b-jtbd.md
+S2. PR-FAQ → 讀取 references/04a-prfaq.md
+S3. North Star Metric + Aha Moment → 讀取 references/05a-northstar-aha.md
+────
+最終產出 → 一頁式方向摘要
+```
+
+## Reference 載入指示
+
+進入各步驟時，讀取對應的 reference 檔案：
+
+| 步驟 | Reference 檔案 |
+|------|---------------|
+| S1 | `references/02b-jtbd.md` |
+| S2 | `references/04a-prfaq.md` |
+| S3 | `references/05a-northstar-aha.md` |
+
+## 最終產出格式
+
+**一頁式方向摘要**：問題 → 解法 → 成功定義，三段式結構，適合快速簡報或同步用。
+
+完成後，依 `references/rules-end-of-flow.md` 執行流程結束規則。快速模式只問是否需要簡報，不問 PRD 和開發交接包（內容不夠完整）。

package/i18n/zh-TW/references/rules-revision.md

@@ -0,0 +1,64 @@
+# 🔄 改版模式步驟序列（共 12 步 + 最終產出）
+
+> 此檔案為改版模式的權威步驟定義。由 SKILL.md 核心派發載入。
+
+## 步驟序列
+
+```
+Phase 0：現況分析
+  S1.  既有產品現況回顧（用戶數據概覽 + 核心指標 + 已知問題 + 安全現況）
+  S2.  現有用戶 JTBD 重新檢驗（哪些 Job 做得好？哪些做不好？）
+
+Phase 1：問題收斂
+  S3.  用戶痛點收集（留存/流失分析 + 用戶反饋彙整 + 行為數據）
+  S4.  痛點彙整表 → 讀取 references/03-define.md → 2.1
+  S5.  Positioning 重新評估 → 讀取 references/03-define.md → 2.2（焦點：定位是否需要調整？）
+  S6.  HMW 問題轉化 → 讀取 references/03-define.md → 2.3
+  S7.  機會評估表 → 讀取 references/03-define.md → 2.4
+
+Phase 2：解法設計
+  S8.  PR-FAQ → 讀取 references/04a-prfaq.md（描述改版後的體驗）
+  S9.  Pre-mortem → 讀取 references/04b-solutions.md → 3.3
+  S10. MVP 範圍 + Not Doing List → 讀取 references/04c-mvp.md（焦點：改什麼 / 不改什麼）
+
+Phase 3：驗證
+  S11. North Star + Aha Moment → 讀取 references/05a-northstar-aha.md（比較改版前後指標）
+  S12. 假設驗證計畫 → 讀取 references/05c-validation-spec.md
+────
+最終產出 → 產品規格摘要（改版版）
+```
+
+### S1 前置：產品上下文載入
+
+進入 S1 前，讀取 `references/rules-context.md` 並檢查 `.product-context.md`：
+
+- **有完整上下文（情境 1）**：自動帶入 PMF 等級、North Star、已知痛點、安全現況、近 3 筆 Decision History。S1 引導改為**差異式**：「上次評估時，你的 PMF 等級為 [X]，北極星指標為 [Y]。目前這些有變化嗎？最新的 DAU/MAU 和留存率是多少？」— 已有的歷史決策和已知痛點不需要重新收集
+- **無上下文（情境 2）**：觸發 Context Bootstrap（`rules-context.md` Section 4，Round 1 + 3），完成後再進入下方標準 S1 數據收集
+- **部分上下文（情境 3）**：從 Decision History 帶入功能變更歷史（知道哪些模組被改過、有哪些風險被識別過），但需詢問整體產品策略和指標（之前只做過功能擴充，缺全局視角）
+
+### S1 標準引導
+
+> 改版模式的 S1 會主動詢問使用者提供既有產品數據：DAU/MAU、留存率、主要用戶反饋、過去版本的關鍵決策等。若 context 已預填部分答案，改為確認而非重新收集。
+> S1 同時收集安全現況：現有認證/授權機制、已知安全漏洞或技術債、近期安全事件。這些資訊會影響改版的風險評估和 Pre-mortem。
+
+### 快速路徑
+
+當使用者在 S1 已提供充分數據（含用戶反饋、指標、痛點），S4-S7（痛點→定位→HMW→機會評估）可在單次對話中連續產出，中間只需一次確認而非四次。觸發條件：S3 收集到的痛點清單已有明確的優先級和數據支持。Hard Gate 規則不變 — 每個步驟的產出仍須完整呈現，只是確認節奏加快。
+
+## Reference 載入指示
+
+| 步驟 | Reference 檔案 |
+|------|---------------|
+| S1-S3 | 無需外部 reference（直接引導使用者提供數據） |
+| S4-S7 | `references/03-define.md` |
+| S8 | `references/04a-prfaq.md` |
+| S9 | `references/04b-solutions.md` |
+| S10 | `references/04c-mvp.md` |
+| S11 | `references/05a-northstar-aha.md` |
+| S12 + 最終產出 | `references/05c-validation-spec.md` |
+
+## 最終產出格式
+
+**改版產品規格摘要**：改版前後對照 + 改什麼/不改什麼 + 成功指標
+
+完成後，依 `references/rules-end-of-flow.md` 執行流程結束規則。