product-playbook 1.0.0

package/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/references/rules-import-document.md

@@ -0,0 +1,261 @@
+# Document Import & Parsing Rules
+
+> Loaded when the user uploads a PDF / DOCX / PPTX file, or triggers `/parse [file]`.
+> On first use, load `rules-document-tools.md` first to confirm tools are installed.
+> This rule works in conjunction with `rules-file-integration.md` — that file defines "when to trigger," this file defines "how to parse."
+
+---
+
+## Parsing Goal
+
+Convert any format of input document into **structured Markdown** for use in subsequent flows:
+- Feature Extension / Revision mode S1 context collection
+- Incremental update source document baseline
+- General document content extraction
+
+---
+
+## PDF Parsing: Three-Layer Strategy + Per-Page Detection
+
+### Overview
+
+```
+Input PDF
+  │
+  ▼
+pymupdf per-page text extraction (zero cost)
+  │
+  ├── Page text > 30 characters → ✅ Convert directly to Markdown (Layer 1)
+  │
+  └── Page text ≤ 30 characters (blank / vector paths / scanned)
+        │
+        ├── Default → Claude Vision semantic parsing (Layer 2)
+        │
+        └── Vision unavailable / Token budget insufficient → Tesseract OCR (Layer 3)
+```
+
+### Step 1: Per-Page Type Detection
+
+**Key principle**: Detect at the "page" level, not the entire document. A single PDF may mix digital text pages and scanned image pages.
+
+```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:
+        # Layer 1: Digital text, extract directly
+        page_results[i] = {"type": "digital", "text": text}
+    else:
+        # Needs Vision or 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 analysis: {total_pages} pages, {digital_count} directly extractable, {vision_count} require visual parsing")
+```
+
+### Step 2: Large File Handling Strategy
+
+| Condition | Strategy |
+|-----------|----------|
+| All pages are digital (vision_count = 0) | Extract all pages directly, zero cost |
+| vision_count ≤ 20 | Read all pages needing visual parsing at once with Claude Vision |
+| vision_count > 20 | Process in batches (≤ 20 pages each), merge results |
+| Total pages > 50 and vision_count > 20 | Ask the user whether to parse the full document or specify a page range |
+
+**Large file (>50 pages) user confirmation prompt**:
+
+```
+📄 This PDF has {total_pages} pages:
+  • {digital_count} pages can be directly extracted (free)
+  • {vision_count} pages require visual parsing (consumes Vision tokens)
+
+Please choose:
+  1️⃣ Full document parsing (complete but consumes more tokens)
+  2️⃣ Parse specific pages only (enter page ranges, e.g. 1-10,15,20-25)
+  3️⃣ Extract only directly extractable pages (skip scanned/vector pages)
+```
+
+### Step 3: Layer 1 — pymupdf Direct Extraction
+
+```python
+def extract_digital_pages(doc, page_results):
+    """Extract all digital text pages"""
+    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)
+```
+
+### Step 4: Layer 2 — Claude Vision Semantic Parsing
+
+For `needs_vision` type pages, first render to PNG with pymupdf, then read with Claude's Read tool.
+
+**Render to image**:
+```python
+def render_pages_to_png(doc, page_indices, dpi=300):
+    """Render specified pages to 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 parsing prompt**:
+
+For each page requiring visual parsing (or batch), after reading the PNG with the Read tool, convert using the following prompt:
+
+```
+You are reading page {page_num}/{total_pages} of a PDF document.
+Please convert the content of this page precisely into Markdown format.
+
+Strict rules:
+1. Tables → Markdown table (preserve all columns, rows, and alignment)
+2. Headings → # / ## / ### corresponding to original level
+3. Numbered lists → 1. 2. 3. (preserve original numbering)
+4. Bullet points → - or •
+5. Bold/Italic → **bold** / *italic*
+6. Charts/Images → > [Chart: brief description]
+7. Headers, footers, page numbers → Ignore
+8. Numbers, dates, names, account numbers → Must be 100% accurate, do not guess
+9. Do not add content not present in the original
+10. Do not translate — preserve the original language
+```
+
+> **Why this is better than OCR**: Claude understands the "semantic structure" of tables (which row is the header, which columns are aligned), whereas Tesseract can only recognize characters one by one and then attempt to reconstruct tables with rules, which often fails.
+
+### Step 5: Layer 3 — Tesseract OCR Fallback
+
+Use only in the following situations:
+- User explicitly requests token conservation
+- Claude Vision is unavailable (API limitations, etc.)
+- Offline environment
+
+```python
+import subprocess
+from PIL import Image
+
+def ocr_page(png_path, lang="chi_tra+eng"):
+    """Tesseract OCR single page"""
+    # macOS tesseract may not read PNG directly, convert to TIFF or use 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 notes (from practical experience)**:
+- On macOS, tesseract may not read PNG files directly — use `stdin` pipe or convert to TIFF first
+- Recommended resolution: 300dpi
+- `chi_tra+eng` language pack recognizes both Traditional Chinese and English simultaneously
+- OCR results need post-processing: merge broken lines, repair table structure
+
+### Step 6: Merge All Pages
+
+```python
+def merge_all_pages(digital_md, vision_md_list):
+    """Merge all pages' Markdown in page order"""
+    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
+
+    # Sort by page number and merge
+    final_md = []
+    for i in sorted(all_pages.keys()):
+        final_md.append(all_pages[i])
+
+    return "\n\n---\n\n".join(final_md)
+```
+
+### Step 7: Output and Notify User
+
+```
+📄 PDF parsing complete:
+  • Total pages: {total_pages}
+  • Direct extraction: {digital_count} pages (pymupdf)
+  • Visual parsing: {vision_count} pages (Claude Vision)
+  • Output: {output_path} (Markdown, {word_count} words)
+```
+
+---
+
+## DOCX Parsing
+
+```bash
+pandoc "{input_path}" -t markdown -o "/tmp/parsed-{timestamp}.md" --wrap=none
+```
+
+**Post-processing**:
+- Remove excess blank lines generated by Pandoc
+- Verify table formatting is correct
+
+---
+
+## PPTX Parsing
+
+```bash
+pandoc "{input_path}" -t markdown -o "/tmp/parsed-{timestamp}.md" --wrap=none
+```
+
+> Pandoc converts each slide into a `##` heading section.
+
+---
+
+## HTML Parsing
+
+```bash
+pandoc "{input_path}" -f html -t markdown -o "/tmp/parsed-{timestamp}.md" --wrap=none
+```
+
+---
+
+## Image Parsing
+
+Use the Claude Read tool directly to read the image, then convert to Markdown using the Vision parsing prompt.
+
+---
+
+## Coordination with rules-file-integration.md
+
+When `rules-file-integration.md` detects the following scenarios, this rule is loaded:
+
+| Scenario | Action |
+|----------|--------|
+| User uploads PDF during Feature Extension S1 | Load this rule → Parse PDF → Extract existing system context |
+| User uploads old PRD during Revision S1 | Load this rule → Parse PDF → Use as revision baseline |
+| User uses `/parse` command | Load this rule → Parse specified file → Output Markdown |
+| User uploads market report PDF | Load this rule → Extract key information → Integrate into corresponding step |
+
+### Source Document Identification
+
+After parsing is complete, if the file is identified as a "source document" (PRD, spec, etc.), automatically mark it:
+
+```
+📎 Source document detected — final output will be an incremental update based on this file.
+  Document structure: {section_count} sections, {table_count} tables
+  Format conventions: [identified formatting characteristics]
+```
+
+The document structure is recorded for use by `rules-export-document.md` during final output.

package/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/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/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/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` 執行流程結束規則。