product-playbook 1.0.0

package/references/rules-document-tools.md

@@ -0,0 +1,126 @@
+# Document Conversion Tool Dependency Management
+
+> Loaded on first trigger of `/export` or `/parse` command.
+
+## Dependency Tiers
+
+| Tier | Tool | Purpose | Installation | Size |
+|------|------|---------|-------------|------|
+| **Core (Zero Install)** | Claude Read tool (Vision) | PDF semantic parsing | Built-in | 0 |
+| **Core (Zero Install)** | Playwright MCP | PDF rendering | Built-in | 0 |
+| **Basic** | pymupdf (fitz) | PDF text extraction + image rendering | `pip3 install --break-system-packages pymupdf` | ~23MB |
+| **Basic** | pikepdf | PDF bookmark injection + metadata | `pip3 install --break-system-packages pikepdf` | ~5MB |
+| **Extended** | pandoc | DOCX / PPTX conversion | `brew install pandoc` | ~50MB |
+| **Fallback** | tesseract + chi_tra | Offline OCR (when Vision is unavailable) | `brew install tesseract tesseract-lang` | ~150MB |
+| **Advanced** | python-docx | High-quality DOCX output | `pip3 install --break-system-packages python-docx` | ~5MB |
+
+## Startup Detection Flow
+
+When the user first triggers a document conversion feature, detect and install as needed in the following order:
+
+### Step 1: Determine Which Tools Are Needed
+
+| User Action | Required Tools |
+|-------------|---------------|
+| `/export pdf` | pymupdf + pikepdf + Playwright MCP |
+| `/export docx` or `/export pptx` | pandoc |
+| `/parse [PDF file]` | pymupdf (+ Claude Vision or tesseract) |
+| `/parse [DOCX/PPTX file]` | pandoc |
+
+### Step 2: Detect Installed Tools
+
+Run the following Bash commands (silent detection, no output displayed):
+
+```bash
+# pymupdf
+python3 -c "import fitz; print(fitz.version)" 2>/dev/null && echo "pymupdf: OK" || echo "pymupdf: MISSING"
+
+# pikepdf
+python3 -c "import pikepdf; print(pikepdf.__version__)" 2>/dev/null && echo "pikepdf: OK" || echo "pikepdf: MISSING"
+
+# pandoc
+which pandoc >/dev/null 2>&1 && echo "pandoc: OK" || echo "pandoc: MISSING"
+
+# tesseract (only detect when explicitly needed)
+which tesseract >/dev/null 2>&1 && tesseract --list-langs 2>&1 | grep -q chi_tra && echo "tesseract: OK" || echo "tesseract: MISSING"
+```
+
+### Step 3: Auto-Install Missing Tools
+
+If missing tools are detected, display the following message and install automatically:
+
+```
+📦 Document conversion requires the following tools:
+  ☐ [Tool name] ([purpose], [size])
+  ...
+Installing, please wait...
+```
+
+Run installation commands in sequence:
+
+```bash
+# pymupdf + pikepdf (install together)
+pip3 install --break-system-packages pymupdf pikepdf
+
+# pandoc
+brew install pandoc
+
+# tesseract (only when offline OCR is needed)
+brew install tesseract tesseract-lang
+```
+
+After installation completes, display:
+```
+✅ Tool installation complete, continuing...
+```
+
+### Step 4: Detect Playwright MCP
+
+Playwright MCP is a core dependency for PDF rendering. Detection method:
+
+1. Attempt to call `mcp__plugin_playwright_playwright__browser_run_code`
+2. If MCP is available → use normally
+3. If MCP is unavailable (not connected) → display:
+
+```
+⚠️ Playwright MCP is not connected. PDF rendering requires the Playwright browser.
+Please do one of the following:
+  1. Start Playwright MCP (recommended)
+  2. Or run ! npx playwright install chromium to install local Chromium
+```
+
+**Playwright Fallback** (when MCP is unavailable):
+
+If the user has installed local Chromium, use Bash to run a Node.js script for PDF rendering:
+```bash
+node -e "
+const { chromium } = require('playwright');
+(async () => {
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+  await page.setContent(require('fs').readFileSync('/tmp/export.html', 'utf8'));
+  await page.pdf({ path: '${OUTPUT_PATH}', format: 'A4', printBackground: true,
+    margin: { top: '1.8cm', bottom: '1.8cm', left: '2cm', right: '2cm' } });
+  await browser.close();
+})();
+"
+```
+
+## Tool State Cache
+
+First detection results are recorded in memory (to avoid repeated detection):
+- Within the same conversation session, confirmed installed tools are not re-detected
+- If installation fails, record the error message and retry on the next trigger
+
+## Platform Compatibility
+
+| Platform | pymupdf | pikepdf | pandoc | tesseract | Playwright |
+|----------|---------|---------|--------|-----------|------------|
+| macOS (Homebrew) | ✅ pip3 | ✅ pip3 | ✅ brew | ✅ brew | ✅ MCP/npx |
+| Linux (apt) | ✅ pip3 | ✅ pip3 | ✅ apt | ✅ apt | ✅ MCP/npx |
+| Windows (WSL) | ✅ pip3 | ✅ pip3 | ✅ choco | ✅ choco | ✅ MCP/npx |
+
+Automatically select the corresponding package manager based on the user's operating system. Detection method:
+```bash
+[[ "$(uname)" == "Darwin" ]] && echo "macOS" || echo "Linux"
+```

package/references/rules-end-of-flow.md

@@ -0,0 +1,150 @@
+# 🏁 流程結束規則
+
+> 所有步驟完成時載入。
+
+## ⛔ 結束條件檢查
+
+產出最終整合內容前，必須先執行：
+
+1. 確認進度指示器中所有步驟都已標記 ✅
+2. 若有步驟被跳過（使用者明確要求），在最終產出中標記「⚠️ 已跳過」
+3. 若有步驟標記為 ⬜（未執行），不得進入最終產出
+4. **安全性快速檢查**：若使用者將進入開發階段（產出開發交接包），在最終產出中附上安全性提醒，並在產出開發交接包時自動讀取 `references/08-security-checklist.md` 生成對應的安全架構段落
+
+違反此規則的行為：自行判斷「剩下的步驟不重要」而跳過、將未完成的步驟標記為已完成、合併多個步驟一次產出。
+
+## 🔍 決策一致性檢查
+
+在產出最終整合內容之前，掃描所有已完成的步驟，驗證跨步驟的一致性：
+
+### 依模式檢查項目
+
+**🚀 快速模式**（3 步驟 — 檢查 2 項交叉引用）：
+1. JTBD ↔ PR-FAQ：PR-FAQ 是否針對與 JTBD 陳述相同的問題？
+2. PR-FAQ ↔ North Star：北極星指標是否衡量了 PR-FAQ 承諾的成果？
+
+**📦 完整模式**（20 步驟 — 檢查全部 7 項）：
+1. 目標使用者 — 在 JTBD、定位、PR-FAQ 和 North Star 中是否引用相同的人物誌？
+2. 核心問題 / JTBD — PR-FAQ 針對相同問題？MVP 是否解決？
+3. 定位 — 是否反映在 PR-FAQ 標題和解法方向中？
+4. 解法方向 — 選出的解法是否與 MVP 範圍一致？
+5. MVP 範圍 — 是否與 PR-FAQ 承諾一致？「不做」的項目是否被遵守？
+6. North Star Metric — 是否衡量 JTBD 成果？在 MVP 範圍內是否可達成？
+7. Pre-mortem 風險 — 鑑於最終解法和 MVP，是否仍然相關？
+
+**🔄 改版模式**（12 步驟 — 檢查 4 項）：
+1. 既有 JTBD ↔ 痛點 ↔ 定位：重新評估後是否一致？
+2. PR-FAQ ↔ MVP 範圍：改版範圍是否與 PR-FAQ 描述一致？
+3. North Star ↔ 改版前後：指標比較是否合乎邏輯？
+4. Pre-mortem 風險：對改版後的產品是否仍然相關？
+
+**⚡ 直接實作模式**（7 步驟 — 檢查 4 項）：
+1. 問題陳述 ↔ PR-FAQ：是否針對相同問題？
+2. 解法方向 ↔ MVP 範圍：選定解法是否與 MVP 一致？
+3. North Star ↔ MVP：指標在 MVP 範圍內是否可達成？
+4. Pre-mortem 風險：對最終解法是否仍然相關？
+
+**🔧 功能擴充模式**（4 步驟 — 檢查 3 項）：
+1. 問題 ↔ 選定解法：解法是否直接解決所述問題？
+2. 解法 ↔ 執行範圍：範圍是否正確實作選定解法？
+3. 風險評估：已識別的風險對執行範圍是否仍然相關？
+
+**✏️ 自訂模式** — 僅檢查使用者實際執行的步驟之間的交叉引用。跳過未納入自訂選擇的步驟檢查。
+
+### 執行方式
+1. 將每個核心決策列為一行摘要（例如：「目標使用者：早期新創公司創辦人」）
+2. 檢查步驟之間是否存在矛盾或過時的引用
+3. 若發現不一致：
+   - 顯示：「⚠️ 一致性檢查在最終產出前發現 [N] 個問題：」
+   - 列出每個問題及受影響的步驟
+   - 詢問使用者：「是否要在產出最終內容前修正這些問題，還是直接繼續？」
+4. 若全部一致：
+   - 顯示：「✅ 決策一致性檢查通過 — 所有步驟已對齊。」
+   - 繼續產出最終內容
+
+### 為什麼需要這個檢查
+在迭代規劃過程中，使用者可能修改上游決策（例如：更改 JTBD），而部分下游步驟仍保留過時的內容。此檢查能在最終文件產出前捕捉這些落差，避免產出不一致的交付物。
+
+## 📦 產品上下文自動萃取
+
+所有步驟完成後、產出最終整合內容的同時，讀取 `references/rules-context.md` Section 8 執行上下文萃取：
+
+1. **檢查 `.product-context.md` 是否存在**
+   - 不存在 → 建立新檔案
+   - 存在 → 依規則更新（Identity/Core Strategy 覆寫，Decision History 追加，Architecture 合併，Insights 合併去重）
+
+2. **萃取內容**（依流程類型對應 `rules-context.md` Section 8 表格）
+
+3. **告知使用者**：在最終產出後顯示：
+   「✅ 產品上下文已更新至 `.product-context.md`，下次規劃時將自動載入。」
+
+4. **版控提醒**（僅首次建立時）：
+   「⚠️ 建議將 `.product-context.md` 加入 `.gitignore`，此檔案可能包含敏感的產品策略資訊。」
+
+## 最佳切入點分析（完整模式適用）
+
+```
+[Persona 痛點] → [JTBD 陳述] → [OST 機會] → [HMW 問題]
+    → [定位（April Dunford）] → [PR-FAQ 驗證] → [解法選定]
+        → [Aha Moment] → [北極星指標] → [PMF 等級判定]
+```
+
+分析要點：最值得解決的問題 / 核心 JTBD / 產品定位 / PMF 等級與下一里程碑 / 第一步行動 / Pre-mortem 風險警示
+
+## 各模式最終產出
+
+| 模式 | 最後自動整合產出 |
+|------|----------------|
+| 🔧 功能擴充模式 | 功能開發規格：問題 → 選定解法 → 影響範圍 → 執行範圍 → 風險 |
+| 🚀 快速模式 | 一頁式方向摘要：問題 → 解法 → 成功定義 |
+| 📦 完整模式 | 最佳切入點分析 ＋ 產品規格摘要 |
+| 🔄 改版模式 | 改版產品規格摘要：改版前後對照 + 改什麼/不改什麼 + 成功指標 |
+| ✏️ 自訂模式 | 產品規格摘要（未執行欄位標記「未執行」） |
+| ⚡ 直接實作模式 | 工程師導向的執行摘要 |
+
+### 產出語言覆寫
+
+使用者可以要求以不同於規劃會議的語言產出文件：
+- 「用日文產出 PR-FAQ」
+- 「用西班牙文輸出報告」
+- 「用中文撰寫 PRD」
+
+當收到語言覆寫請求時：
+1. 以請求的語言生成產出內容
+2. 保持框架名稱為英文（JTBD、PR-FAQ、North Star 等）
+3. 產出完成後回到規劃會議的原始語言
+4. 注意：這僅影響產出文件的語言，不影響參考檔案或規劃流程
+
+## 延伸產出詢問
+
+完成最終整合產出後，主動詢問：
+
+```
+「企劃內容已整合完成！需要我幫你產出以下文件嗎？
+
+□ 更新版 [文件類型]（基於上傳的原始文件增量更新）← 僅在有上傳原始文件時顯示
+□ PDF 文件（專業排版，含書籤導航，適合正式分享）
+□ HTML 企劃報告（互動式，適合線上分享）
+□ Word 文件（適合協作編輯）
+□ PRD 工程師交付包（含流程圖、DB schema、UI wireframe）
+□ 簡報 PPTX（適合會議報告，產出後建議用 Keynote / PowerPoint 美化）
+□ 開發交接包（CLAUDE.md + TASKS.md + TICKETS.md + 技術架構，可直接在 Claude Code 中開始開發）
+□ 以上都要
+
+也可以說「不用」直接結束，或指定特定文件。
+也可以隨時使用 /export [pdf|docx|pptx|html|md] 匯出。」
+```
+
+**選項顯示規則**：
+- 有上傳原始文件 → 「更新版 [文件類型]」列在最前，標註「（推薦）」
+- 產出對象為工程師 → PRD 和開發交接包排前
+- 產出對象為老闆/高層 → PDF 和簡報排前
+- 產出對象為跨部門 → PDF、HTML 報告和簡報都列出
+- 快速模式 → 只問是否需要 PDF 或簡報
+- 產出對象為自己 → 開發交接包排第一位
+
+**匯出觸發規則**：
+- 使用者選擇 PDF / Word / 簡報 PPTX → 載入 `rules-export-document.md`
+- 首次觸發文件匯出 → 先載入 `rules-document-tools.md` 檢查並安裝必要工具
+- 使用者選擇 HTML 企劃報告 → 載入 `06-html-report.md`（現有規則）
+- 使用者選擇「以上都要」→ 依序執行各格式匯出

package/references/rules-export-document.md

@@ -0,0 +1,346 @@
+# Multi-Format Document Export Rules
+
+> Loaded when the user triggers `/export [format]` or selects an export format after the flow ends.
+> On first use, load `rules-document-tools.md` first to confirm tools are installed.
+
+## Supported Export Formats
+
+| Format | Command | Conversion Path | Tools |
+|--------|---------|----------------|-------|
+| PDF | `/export pdf` | HTML+CSS → Playwright → pikepdf bookmarks | Playwright MCP + pikepdf |
+| DOCX | `/export docx` | MD → Pandoc | pandoc + reference.docx |
+| PPTX | `/export pptx` | MD → Pandoc | pandoc |
+| HTML | `/export html` | Existing `06-html-report.md` rules | Built-in |
+| Markdown | `/export md` | Direct output | Built-in |
+
+---
+
+## PDF Export (Core Flow)
+
+### Path Selection
+
+PDF export has two paths, automatically selected based on source content:
+
+| Source | Path | Reason |
+|--------|------|--------|
+| Planning output direct export (PRD / incremental update / spec) | **Path A: setContent** | No external JS dependencies, all resources can be inlined |
+| HTML planning report to PDF (with Mermaid diagrams / CDN fonts) | **Path B: HTTP Server** | Needs to load external JS (mermaid.js) and CDN fonts |
+
+### Path A: Standalone Document → PDF (setContent)
+
+Applicable to: PRD, feature extension incremental updates, specs, any content without external JS.
+
+**Step 1: Generate HTML Content**
+
+Claude reads `references/templates/prd-style.css` and generates a complete HTML document:
+
+```html
+<!DOCTYPE html>
+<html lang="zh-TW">
+<head>
+<meta charset="UTF-8">
+<style>
+/* Read the full contents of prd-style.css and inline here */
+</style>
+</head>
+<body>
+
+<!-- Cover page -->
+<div class="cover-page">
+  <h1>[Document Title]</h1>
+  <div class="subtitle">[Subtitle or one-line description]</div>
+  <div class="version-badge">[Version Number]</div>
+  <div class="meta-info">
+    <strong>PM</strong> [PM Name]<br>
+    <strong>Date</strong> [ISO Date]<br>
+    <strong>Status</strong> [Status]
+  </div>
+</div>
+
+<!-- Legend (only for incremental update documents) -->
+<div class="diff-legend">
+  <div class="diff-legend-item"><div class="diff-legend-swatch swatch-new"></div> New in this version</div>
+  <div class="diff-legend-item"><div class="diff-legend-swatch swatch-upd"></div> Modified in this version</div>
+  <div class="diff-legend-item"><div class="diff-legend-swatch swatch-unchanged"></div> Unchanged</div>
+</div>
+
+<!-- Table of Contents page -->
+<div class="toc-page">
+  <h2>Table of Contents</h2>
+  <ul class="toc">
+    <!-- Claude auto-generates TOC items based on h2 headings -->
+    <li>
+      <span class="toc-title">[Section Name]</span>
+      <span class="toc-dots"></span>
+      <span class="toc-page-num">[Page Number]</span>
+    </li>
+  </ul>
+</div>
+
+<!-- Body content -->
+[Body HTML]
+
+<!-- Footer -->
+<div class="doc-footer">
+  [Document Code] [Version] ｜ [Date] ｜ Generated by Product Playbook
+</div>
+
+</body>
+</html>
+```
+
+**Important**:
+- CSS must be fully inlined (no external links)
+- Fonts use system fonts: `"PingFang TC", "Noto Sans TC", system-ui` (Playwright will automatically embed in PDF)
+- No `<script>` tags or external resource references
+- TOC page numbers are estimates (may need fine-tuning after PDF generation)
+
+**Step 2: Playwright Renders PDF**
+
+Save the HTML content to `/tmp/export-{timestamp}.html`, then call Playwright MCP:
+
+```javascript
+// mcp__plugin_playwright_playwright__browser_run_code
+async (page) => {
+  const fs = require('fs');
+  const html = fs.readFileSync('/tmp/export-{timestamp}.html', 'utf8');
+  await page.setContent(html, { waitUntil: 'networkidle' });
+  await page.pdf({
+    path: '{output_path}',
+    format: 'A4',
+    margin: { top: '1.8cm', bottom: '1.8cm', left: '2cm', right: '2cm' },
+    printBackground: true,
+    displayHeaderFooter: true,
+    headerTemplate: '<div></div>',
+    footerTemplate: '<div style="font-size:8pt;color:#999;text-align:center;width:100%;">p.<span class="pageNumber"></span> / <span class="totalPages"></span></div>'
+  });
+  return 'PDF generated';
+}
+```
+
+> Note: If the HTML content is too large (>500KB), setContent may time out. In that case, switch to Path B (HTTP Server).
+
+**Step 3: pikepdf Bookmark Injection**
+
+```python
+import pikepdf, re
+
+pdf = pikepdf.open('{output_path}')
+
+# Extract h2 headings from HTML as bookmarks
+# Claude should record the estimated page number for each h2 when generating HTML
+bookmarks = [
+    # (title, page index 0-based)
+    ("Revision History", 2),
+    ("User Story", 4),
+    ("Development Architecture", 6),
+    # ... generated based on actual content
+]
+
+with pdf.open_outline() as outline:
+    for title, page_idx in bookmarks:
+        page_idx = min(page_idx, len(pdf.pages) - 1)
+        outline.root.append(
+            pikepdf.OutlineItem(title, page_idx)
+        )
+
+# Set PDF metadata
+with pdf.open_metadata() as meta:
+    meta['dc:title'] = '[Document Title]'
+    meta['dc:creator'] = ['[PM Name]']
+    meta['pdf:Producer'] = 'Product Playbook + Playwright'
+
+pdf.save('{output_path}')
+```
+
+**Step 4: Notify User**
+
+```
+✅ PDF exported to: {output_path}
+  📄 {page_count} pages ｜ {file_size}
+  📑 Includes bookmark navigation ({bookmark_count} sections)
+```
+
+### Path B: HTML Report → PDF (HTTP Server)
+
+Applicable to: HTML reports with Mermaid diagrams, CDN fonts, interactive elements.
+
+**Step 1: HTML Report Already Generated**
+
+The HTML report is generated by `06-html-report.md` rules and saved as `/tmp/report-{timestamp}.html`.
+
+**Step 2: Start HTTP Server**
+
+```bash
+cd /tmp && python3 -m http.server 18899 &
+echo $!  # Record PID
+```
+
+**Step 3: Playwright Rendering**
+
+```javascript
+// mcp__plugin_playwright_playwright__browser_run_code
+async (page) => {
+  await page.goto('http://localhost:18899/report-{timestamp}.html', {
+    waitUntil: 'networkidle',
+    timeout: 30000
+  });
+  // Wait for Mermaid chart rendering to complete
+  await page.waitForTimeout(3000);
+  // Expand all accordion (<details>) elements
+  await page.evaluate(() => {
+    document.querySelectorAll('details').forEach(d => d.open = true);
+  });
+  await page.pdf({
+    path: '{output_path}',
+    format: 'A4',
+    margin: { top: '1.8cm', bottom: '1.8cm', left: '2cm', right: '2cm' },
+    printBackground: true,
+    displayHeaderFooter: true,
+    headerTemplate: '<div></div>',
+    footerTemplate: '<div style="font-size:8pt;color:#999;text-align:center;width:100%;">p.<span class="pageNumber"></span> / <span class="totalPages"></span></div>'
+  });
+  return 'PDF generated';
+}
+```
+
+**Step 4: Shut Down HTTP Server + pikepdf Bookmarks**
+
+```bash
+kill {SERVER_PID}
+```
+
+Then perform the same pikepdf bookmark injection step as Path A.
+
+### Playwright MCP Unavailable Fallback
+
+If Playwright MCP is not connected, use Node.js directly:
+
+```bash
+node -e "
+const { chromium } = require('playwright');
+const fs = require('fs');
+(async () => {
+  const browser = await chromium.launch({ headless: true });
+  const page = await browser.newPage();
+  const html = fs.readFileSync('/tmp/export-{timestamp}.html', 'utf8');
+  await page.setContent(html, { waitUntil: 'networkidle' });
+  await page.pdf({
+    path: '${OUTPUT_PATH}',
+    format: 'A4',
+    printBackground: true,
+    margin: { top: '1.8cm', bottom: '1.8cm', left: '2cm', right: '2cm' }
+  });
+  await browser.close();
+  console.log('PDF generated');
+})();
+"
+```
+
+---
+
+## DOCX Export
+
+### Step 1: Generate Markdown
+
+Claude organizes the planning output into clean Markdown format and saves it as `/tmp/export-{timestamp}.md`.
+
+### Step 2: Pandoc Conversion
+
+```bash
+pandoc /tmp/export-{timestamp}.md \
+  -o "{output_path}" \
+  --from markdown \
+  --to docx \
+  --reference-doc="~/.claude/skills/product-playbook/references/templates/reference.docx" \
+  --toc \
+  --toc-depth=2
+```
+
+If no reference.docx template is available, omit the `--reference-doc` parameter (uses Pandoc default styles).
+
+### Step 3: Notify User
+
+```
+✅ Word document exported to: {output_path}
+  📄 Includes table of contents ｜ {file_size}
+```
+
+---
+
+## PPTX Export
+
+```bash
+pandoc /tmp/export-{timestamp}.md \
+  -o "{output_path}" \
+  --from markdown \
+  --to pptx \
+  --slide-level=2
+```
+
+> Tip: Pandoc PPTX quality is limited. It's recommended to use the PPTX as an outline, then polish it with PowerPoint/Keynote.
+
+---
+
+## Special Handling for Incremental Update Documents
+
+When exporting Feature Extension or Revision mode incremental update documents:
+
+### Diff Visual Marking Rules
+
+1. **Paragraphs marked `[NEW]`**:
+   - Use `<span class="new">NEW</span>` marker
+   - Table rows get `class="new-row"`
+   - Paragraphs get `class="diff-added"`
+
+2. **Paragraphs marked `[UPDATED]`**:
+   - Use `<span class="upd">UPDATED</span>` marker
+   - Table rows get `class="upd-row"`
+   - If original content exists, original content gets `class="diff-removed"`, new content gets `class="diff-added"`
+
+3. **Unchanged paragraphs**: Display normally, no special markers
+
+4. **Legend at document start**:
+```html
+<div class="diff-legend">
+  <div class="diff-legend-item">
+    <div class="diff-legend-swatch swatch-new"></div> New in this version
+  </div>
+  <div class="diff-legend-item">
+    <div class="diff-legend-swatch swatch-upd"></div> Modified in this version
+  </div>
+  <div class="diff-legend-item">
+    <div class="diff-legend-swatch swatch-unchanged"></div> No marker = Unchanged
+  </div>
+</div>
+```
+
+---
+
+## Output Path Rules
+
+Default output to `~/Downloads/`, filename format:
+
+```
+[Document Code] [Document Title] [Version].{ext}
+
+Examples:
+[D-221] Virtual Account v1.0.14 Full Merged Version.pdf
+Product Planning Report - UPASS Virtual Account.docx
+```
+
+If the user specifies a path, use the user-specified path.
+
+---
+
+## Quality Checklist
+
+Before export, Claude self-checks:
+
+- [ ] No residual Markdown syntax in HTML (`**`, `##`, `|---|`)
+- [ ] All table row and column counts match the original content
+- [ ] `[NEW]` / `[UPDATED]` markers correctly mapped to corresponding CSS classes
+- [ ] Cover page information (title, version, PM, date) is correct
+- [ ] TOC items match the body h2 headings
+- [ ] CSS is fully inlined (Path A) or CDN is accessible (Path B)
+- [ ] Bookmark count matches h2 heading count

package/references/rules-file-integration.md

@@ -0,0 +1,65 @@
+# 📎 File Integration Guide
+
+> Loaded when the user uploads supplementary materials.
+
+## Directly Supported File Types
+
+| File Type | Common Scenarios | Integration Method |
+|-----------|-----------------|-------------------|
+| **Images** | Competitor screenshots, whiteboard photos, hand-drawn journey maps, app interface screenshots, data report screenshots | Recognize content and integrate into the corresponding step |
+| **PDF** | Market reports, internal documents, user research reports, legacy PRDs | Load `rules-import-document.md` for three-layer parsing (pymupdf direct extraction → Claude Vision semantic parsing → Tesseract fallback). On first use, load `rules-document-tools.md` to check tools. |
+| **CSV / Excel** | User behavior data, retention data, NPS survey results, sales data | Analyze data and use for quantitative assessment |
+| **Text files** | Interview transcripts, existing requirements documents, meeting notes | Extract Persona clues, pain points, JTBD evidence |
+| **DOCX** | Existing PRDs, product spec documents, user research reports | Load `rules-import-document.md`, use Pandoc to convert to Markdown then integrate. On first use, load `rules-document-tools.md` to check tools. |
+| **PPTX** | Existing presentations, product intro slides | Load `rules-import-document.md`, use Pandoc to convert to Markdown then integrate. |
+
+## Not Directly Supported but Guidance Available
+
+| File Type | Guidance |
+|-----------|----------|
+| **Video** | Ask the user to describe key scenes, or provide a transcript/subtitle file |
+| **Figma / Sketch** | Ask the user to take screenshots and upload them |
+| **Protobuf / Swagger** | Ask the user to export as JSON or text format |
+
+## File → Step Auto-Mapping Table
+
+| Uploaded Content | Auto-Mapped Step | Integration Action |
+|-----------------|-----------------|-------------------|
+| Competitor app / website screenshots | Positioning | Identify as "competitive alternatives," analyze differentiation |
+| Whiteboard hand-drawn flowchart | Journey Map / OST | Recognize the flow and convert into a structured table |
+| User interview transcript | Persona + JTBD | Extract pain points, current workarounds, emotional reactions, Job statements |
+| User behavior data (CSV) | Opportunity Assessment + North Star + PMF | Replace assumption-based scores with real data |
+| NPS / satisfaction survey | PMF + Sean Ellis Score | Directly calculate the Score; determine PMF level |
+| Existing PRD / requirements document | Revision Mode S1 + MVP | Extract existing feature list and decision history |
+| Market report PDF | Opportunity Assessment + Strategy | Extract market size, trends, competitive landscape |
+| Sales data | Business Model + GTM | Analyze revenue structure, customer distribution, channel effectiveness |
+| App interface screenshots | Aha Moment + Journey | Analyze the current experience path |
+
+## Integration Rules
+
+1. **Proactive identification**: First explain "I see you uploaded [file type]. I will integrate the [key information] from it into [step name]."
+2. **Do not overwrite existing output**: Mark the uploaded content as "supplementary material," update the output, and trigger the change propagation rules
+3. **Mark the source**: Annotate in the output which content came from the uploaded file (e.g., "✦ From the uploaded user research report")
+4. **Data takes priority**: When real data conflicts with previous assumptions, defer to the real data
+5. **Cross-step impact**: A single file may affect multiple steps — list all affected steps at once
+
+## 📎 Source Document Identification & Incremental Update
+
+When a user uploads a file during **Feature Extension** or **Revision Mode**, determine if it is a "source document" (a document that should be incrementally updated with the new planning output):
+
+### Identification Criteria
+- File type: PRD, product spec, architecture doc, requirements doc, design doc
+- User explicitly says: "this is our current PRD", "update this document", "build on this spec", etc.
+- Uploaded during S1 (context collection) of Feature Extension or Revision Mode
+
+### When a Source Document Is Identified
+1. Mark it: "📎 Source document detected — final output will be an incremental update based on this file"
+2. Parse the document structure (section headings, formatting conventions, naming patterns)
+3. Record the document's format and style for consistent output
+4. During S1, use the document to pre-fill existing system context (tech stack, modules, features)
+
+### Incremental Output Rules (applied at Final Output stage)
+- New content inserted into the appropriate sections, marked with `[NEW]`
+- Modified content marked with `[UPDATED]`, original content preserved as comment
+- Sections unrelated to the new feature remain untouched
+- The output document maintains the original file's format, style, and naming conventions