product-playbook 1.0.0

package/i18n/en/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/i18n/en/references/rules-product-type.md

@@ -0,0 +1,14 @@
+# 🏢 B2B / B2C Differentiation Adjustments
+
+> Loaded after the product type is confirmed. Claude automatically applies the following adjustments within each framework.
+
+| Framework | B2C Adjustments | B2B Adjustments |
+|-----------|----------------|----------------|
+| **Persona** | Segment by personal motivations/habits | Distinguish between "buying decision maker" and "actual end user" as two Persona types; add "organization size" and "procurement process" fields |
+| **JTBD** | Focus on personal emotional and social jobs | Add "organizational-level jobs": What goal does this help the company achieve? What job does the individual accomplish within the organization? |
+| **PMF Assessment** | Primarily based on DAU/MAU, retention rate, Sean Ellis Score | Primarily based on "paying customers + expansion rate + NPS"; Level 1 = 3-5 paying customers |
+| **Aha Moment** | Core value experienced during first use | May not emerge until onboarding/trial period; design a "Time-to-Value" metric |
+| **MVP** | Can be a complete lightweight product | May need to be a Pilot (a customized deployment for a specific customer) |
+| **GTM** | Primarily product-led growth (PLG) or community-driven | Primarily sales-driven or partner channel-driven |
+| **Pricing** | Freemium / Subscription / Usage-based | Annual contract / Per-seat / Usage-based / Custom quote |
+| **North Star** | User activity or core action completion count | ARR, Net Revenue Retention, Active Accounts |

package/i18n/en/references/rules-progress.md

@@ -0,0 +1,60 @@
+# 🔁 Progress Persistence & Interruption Recovery
+
+> Loaded when the user says "pause," "save," or when the skill checks for progress at startup.
+
+## Progress File Format
+
+After each step is completed, create or update `.product-playbook-progress.md` in the project directory:
+
+```
+# Product Playbook Progress Save
+
+- Mode: [Quick Mode / Full Mode / ...]
+- Product type: [B2C / B2B / ...]
+- Product description: [User's product description]
+- Current progress: S[X] / S[Y]
+- Last updated: [timestamp]
+
+## Completed Steps
+
+### S1: [Step name] ✅
+[Core output of this step — retain enough detail so it does not need to be redone upon recovery]
+
+### S2: [Step name] ✅
+[Same as above]
+
+## Pending Steps
+- S3: [Step name]
+- S4: [Step name]
+- ...
+```
+
+### Feature Extension Mode Example
+```markdown
+Mode: Feature Extension
+Step: S2/S4
+S1: Problem + existing system context ✅
+S2: Three parallel solutions + AI recommendation ▶️
+S3: Risk assessment ⬜
+S4: Execution scope ⬜
+```
+
+## Trigger Rules
+
+1. **Auto-save**: After each step is completed and confirmed by the user, immediately update the progress file
+2. **Check on startup**: When the skill is triggered, first check whether `.product-playbook-progress.md` exists. If it does, display:
+```
+Detected unfinished product planning progress ([mode name], S[X]/S[Y]):
+  1️⃣ Continue — Resume from S[X]
+  2️⃣ Start over — Clear old progress and begin from scratch
+(Enter 1 or 2)
+```
+3. **Pause command**: When the user says "pause," "do something else first," or "save," confirm the progress file has been updated and reply: "Progress saved to .product-playbook-progress.md (S[X]/S[Y]). It will be automatically detected next time you start the skill in this project."
+4. **Cleanup on completion**: After the entire flow is completed and final documents are produced, ask the user whether to delete the progress file
+6. **Version control reminder**: When `.product-playbook-progress.md` is created for the first time, remind the user: "⚠️ We recommend adding `.product-playbook-progress.md` to `.gitignore` — this file may contain sensitive product strategy information."
+5. **Interruption save**: When an unrelated prompt is detected during the flow (see SKILL.md flow interruption handling rules), save progress even if the current step is not yet complete. Use 🔶 (in progress) instead of ✅ for the current step in the save format, and preserve the partially produced content:
+```
+### S[X]: [Step name] 🔶 (in progress, partially completed)
+[Partially produced content]
+⚠️ This step is not yet complete — resume from here upon recovery
+```

package/i18n/en/references/rules-quick.md

@@ -0,0 +1,29 @@
+# 🚀 Quick Mode Step Sequence (3 Steps + Final Output)
+
+> This file is the authoritative step definition for Quick Mode. Loaded by the SKILL.md core dispatcher.
+
+## Step Sequence
+
+```
+S1. JTBD Statement → Read references/02b-jtbd.md
+S2. PR-FAQ → Read references/04a-prfaq.md
+S3. North Star Metric + Aha Moment → Read references/05a-northstar-aha.md
+────
+Final Output → One-page direction summary
+```
+
+## Reference Loading Instructions
+
+When entering each step, read the corresponding reference file:
+
+| Step | Reference File |
+|------|---------------|
+| S1 | `references/02b-jtbd.md` |
+| S2 | `references/04a-prfaq.md` |
+| S3 | `references/05a-northstar-aha.md` |
+
+## Final Output Format
+
+**One-page direction summary**: Problem → Solution → Success Definition, a three-part structure suitable for quick briefings or team syncs.
+
+After completion, follow `references/rules-end-of-flow.md` to execute the end-of-flow rules. Quick Mode only asks whether a presentation is needed — it does not offer PRD or dev handoff packages (the content is not comprehensive enough).

package/i18n/en/references/rules-revision.md

@@ -0,0 +1,64 @@
+# 🔄 Revision Mode Step Sequence (12 Steps + Final Output)
+
+> This file is the authoritative step definition for Revision Mode. Loaded by the SKILL.md core dispatcher.
+
+## Step Sequence
+
+```
+Phase 0: Current State Analysis
+  S1.  Existing product review (user data overview + core metrics + known issues + security status)
+  S2.  Re-examine existing user JTBD (which jobs are being done well? which aren't?)
+
+Phase 1: Problem Convergence
+  S3.  User pain point collection (retention/churn analysis + user feedback synthesis + behavioral data)
+  S4.  Pain point summary table → load references/03-define.md → 2.1
+  S5.  Positioning re-evaluation → load references/03-define.md → 2.2 (focus: does positioning need adjustment?)
+  S6.  HMW question reframing → load references/03-define.md → 2.3
+  S7.  Opportunity assessment table → load references/03-define.md → 2.4
+
+Phase 2: Solution Design
+  S8.  PR-FAQ → load references/04a-prfaq.md (describe the post-revision experience)
+  S9.  Pre-mortem → load references/04b-solutions.md → 3.3
+  S10. MVP scope + Not Doing List → load references/04c-mvp.md (focus: what to change / what not to change)
+
+Phase 3: Validation
+  S11. North Star + Aha Moment → load references/05a-northstar-aha.md (compare pre- vs. post-revision metrics)
+  S12. Hypothesis validation plan → load references/05c-validation-spec.md
+────
+Final Output → Product spec summary (revision edition)
+```
+
+### S1 Pre-step: Product Context Loading
+
+Before entering S1, load `references/rules-context.md` and check `.product-context.md`:
+
+- **Full context available (Scenario 1)**: Auto-populate PMF level, North Star, known pain points, security status, and the 3 most recent Decision History entries. S1 guidance switches to **delta mode**: "Last time we assessed, your PMF level was [X] and your North Star metric was [Y]. Has anything changed? What are the latest DAU/MAU and retention numbers?" — Previously collected decision history and known pain points do not need to be re-gathered.
+- **No context available (Scenario 2)**: Trigger Context Bootstrap (`rules-context.md` Section 4, Round 1 + 3), then proceed to standard S1 data collection below.
+- **Partial context (Scenario 3)**: Pull in feature change history from Decision History (know which modules were changed and what risks were identified), but ask about overall product strategy and metrics (previous work only covered feature expansion and lacks a holistic view).
+
+### S1 Standard Guidance
+
+> Revision Mode's S1 proactively asks the user to provide existing product data: DAU/MAU, retention rates, key user feedback, past version decisions, etc. If context already pre-fills some answers, confirm rather than re-collect.
+> S1 also collects current security status: existing auth/authorization mechanisms, known security vulnerabilities or tech debt, recent security incidents. This information affects the revision's risk assessment and Pre-mortem.
+
+### Fast Path
+
+When the user provides sufficient data at S1 (including user feedback, metrics, and pain points), S4–S7 (pain points → positioning → HMW → opportunity assessment) can be produced in a single conversation turn, requiring only one confirmation instead of four. Trigger condition: the pain point list gathered in S3 already has clear prioritization and data support. Hard Gate rules remain unchanged — each step's output must still be fully presented; only the confirmation cadence is accelerated.
+
+## Reference Loading Instructions
+
+| Step | Reference File |
+|------|---------------|
+| S1–S3 | No external reference needed (guide the user to provide data directly) |
+| 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 + Final Output | `references/05c-validation-spec.md` |
+
+## Final Output Format
+
+**Revision Product Spec Summary**: Before/after comparison + what to change / what not to change + success metrics
+
+Upon completion, execute end-of-flow rules per `references/rules-end-of-flow.md`.