product-playbook 1.0.0

package/i18n/ko/references/rules-import-document.md

@@ -0,0 +1,261 @@
+# 문서 가져오기 및 파싱 규칙
+
+> 사용자가 PDF / DOCX / PPTX 파일을 업로드하거나 `/parse [파일]`을 트리거할 때 로드됩니다.
+> 최초 사용 시, 먼저 `rules-document-tools.md`를 로드하여 도구 설치 여부를 확인합니다.
+> 이 규칙은 `rules-file-integration.md`와 함께 작동합니다 — 해당 파일은 "언제 트리거할지"를 정의하고, 이 파일은 "어떻게 파싱할지"를 정의합니다.
+
+---
+
+## 파싱 목표
+
+모든 형식의 입력 문서를 **구조화된 Markdown**으로 변환하여 후속 플로우에 활용:
+- 기능 확장 / 리비전 모드 S1 컨텍스트 수집
+- 증분 업데이트 원본 문서 베이스라인
+- 일반 문서 내용 추출
+
+---
+
+## PDF 파싱: 3계층 전략 + 페이지별 감지
+
+### 개요
+
+```
+입력 PDF
+  │
+  ▼
+pymupdf 페이지별 텍스트 추출 (비용 없음)
+  │
+  ├── 페이지 텍스트 > 30자 → ✅ Markdown으로 직접 변환 (계층 1)
+  │
+  └── 페이지 텍스트 ≤ 30자 (빈 페이지 / 벡터 경로 / 스캔본)
+        │
+        ├── 기본값 → Claude Vision 시맨틱 파싱 (계층 2)
+        │
+        └── Vision 사용 불가 / 토큰 예산 부족 → 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단계: 대용량 파일 처리 전략
+
+| 조건 | 전략 |
+|------|------|
+| 모든 페이지가 디지털 (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 토큰 소모)
+
+선택해 주세요:
+  1️⃣ 전체 문서 파싱 (완전하지만 토큰 소모 증가)
+  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 파싱 프롬프트**:
+
+시각적 파싱이 필요한 각 페이지(또는 배치)에 대해, Read 도구로 PNG를 읽은 후 다음 프롬프트로 변환:
+
+```
+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
+```
+
+> **OCR보다 나은 이유**: Claude는 테이블의 "시맨틱 구조"(어떤 행이 헤더인지, 어떤 열이 정렬되어 있는지)를 이해하지만, Tesseract는 문자를 하나씩 인식한 후 규칙으로 테이블을 재구성하려 시도하며, 이는 자주 실패합니다.
+
+### 5단계: 계층 3 — Tesseract OCR 폴백
+
+다음 상황에서만 사용:
+- 사용자가 토큰 절약을 명시적으로 요청
+- 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 = {}
+    # 디지털 페이지
+    for page_num, md in digital_md.items():
+        all_pages[page_num] = md
+    # vision/ocr 페이지
+    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, {word_count} 단어)
+```
+
+---
+
+## 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 파싱 프롬프트로 Markdown으로 변환합니다.
+
+---
+
+## rules-file-integration.md와의 연동
+
+`rules-file-integration.md`가 다음 시나리오를 감지하면, 이 규칙이 로드됩니다:
+
+| 시나리오 | 작업 |
+|---------|------|
+| 사용자가 기능 확장 S1에서 PDF 업로드 | 이 규칙 로드 → PDF 파싱 → 기존 시스템 컨텍스트 추출 |
+| 사용자가 리비전 S1에서 기존 PRD 업로드 | 이 규칙 로드 → PDF 파싱 → 리비전 베이스라인으로 활용 |
+| 사용자가 `/parse` 명령 사용 | 이 규칙 로드 → 지정된 파일 파싱 → Markdown 출력 |
+| 사용자가 시장 보고서 PDF 업로드 | 이 규칙 로드 → 핵심 정보 추출 → 해당 단계에 통합 |
+
+### 원본 문서 식별
+
+파싱 완료 후, 파일이 "원본 문서" (PRD, 스펙 등)로 식별되면 자동으로 표시:
+
+```
+📎 원본 문서 감지됨 — 최종 산출물은 이 파일을 기반으로 한 증분 업데이트가 됩니다.
+  문서 구조: {section_count}개 섹션, {table_count}개 테이블
+  서식 규칙: [식별된 서식 특성]
+```
+
+문서 구조는 `rules-export-document.md`에서 최종 출력 시 사용하기 위해 기록됩니다.

package/i18n/ko/references/rules-product-type.md

@@ -0,0 +1,14 @@
+# 🏢 B2B / B2C 차별화 조정
+
+> 제품 유형이 확인된 후 로드됩니다. Claude는 각 프레임워크 내에서 다음 조정을 자동으로 적용합니다.
+
+| 프레임워크 | B2C 조정 | B2B 조정 |
+|-----------|---------|---------|
+| **Persona** | 개인 동기/습관으로 세분화 | "구매 의사결정자"와 "실제 최종 사용자"를 두 가지 Persona 유형으로 구분; "조직 규모"와 "구매 프로세스" 필드 추가 |
+| **JTBD** | 개인의 감정적, 사회적 Job에 집중 | "조직 수준 Job" 추가: 이것이 회사의 어떤 목표 달성을 돕는가? 개인이 조직 내에서 어떤 과업을 완수하는가? |
+| **PMF 평가** | 주로 DAU/MAU, 리텐션율, Sean Ellis Score 기반 | 주로 "유료 고객 + 확장율 + NPS" 기반; Level 1 = 유료 고객 3-5명 |
+| **Aha Moment** | 첫 사용 시 핵심 가치 경험 | 온보딩/트라이얼 기간까지 나타나지 않을 수 있음; "Time-to-Value" 지표 설계 |
+| **MVP** | 완전한 경량 제품일 수 있음 | 파일럿(특정 고객을 위한 맞춤 배포)이 필요할 수 있음 |
+| **GTM** | 주로 Product-Led Growth(PLG) 또는 커뮤니티 기반 | 주로 영업 기반 또는 파트너 채널 기반 |
+| **프라이싱** | Freemium / 구독 / 사용량 기반 | 연간 계약 / 사용자당 과금 / 사용량 기반 / 맞춤 견적 |
+| **North Star** | 사용자 활동 또는 핵심 행동 완료 수 | ARR, Net Revenue Retention, 활성 계정 |

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

@@ -0,0 +1,60 @@
+# 🔁 진행 저장 & 중단 복구
+
+> 사용자가 "일시 정지", "저장"이라고 말하거나 시작 시 진행 상황을 점검할 때 로드됩니다.
+
+## 진행 파일 형식
+
+각 단계가 완료된 후, 프로젝트 디렉토리에 `.product-playbook-progress.md`를 생성하거나 업데이트하세요:
+
+```
+# Product Playbook 진행 저장
+
+- 모드: [퀵 모드 / 풀 모드 / ...]
+- 제품 유형: [B2C / B2B / ...]
+- 제품 설명: [사용자의 제품 설명]
+- 현재 진행: S[X] / S[Y]
+- 마지막 업데이트: [타임스탬프]
+
+## 완료된 단계
+
+### S1: [단계명] ✅
+[이 단계의 핵심 산출물 — 복구 시 재작업이 필요 없을 만큼 충분한 세부사항 유지]
+
+### S2: [단계명] ✅
+[위와 동일]
+
+## 대기 중인 단계
+- S3: [단계명]
+- S4: [단계명]
+- ...
+```
+
+### 기능 확장 모드 예시
+```markdown
+모드: 기능 확장
+단계: S2/S4
+S1: 문제 + 기존 시스템 컨텍스트 ✅
+S2: 3가지 병렬 솔루션 + AI 추천 ▶️
+S3: 리스크 평가 ⬜
+S4: 실행 범위 ⬜
+```
+
+## 트리거 규칙
+
+1. **자동 저장**: 각 단계가 완료되고 사용자가 확인한 후, 즉시 진행 파일을 업데이트
+2. **시작 시 점검**: 스킬이 트리거되면, 먼저 `.product-playbook-progress.md`가 존재하는지 확인. 존재하면 표시:
+```
+미완료된 제품 기획 진행이 감지되었습니다 ([모드명], S[X]/S[Y]):
+  1️⃣ 계속 — S[X]에서 재개
+  2️⃣ 처음부터 — 이전 진행 삭제하고 새로 시작
+(1 또는 2를 입력하세요)
+```
+3. **일시 정지 명령**: 사용자가 "일시 정지", "다른 것 먼저", "저장"이라고 말하면, 진행 파일이 업데이트되었음을 확인하고 답변: "진행이 .product-playbook-progress.md에 저장되었습니다 (S[X]/S[Y]). 이 프로젝트에서 다음에 스킬을 시작할 때 자동으로 감지됩니다."
+4. **완료 시 정리**: 전체 플로우가 완료되고 최종 문서가 작성된 후, 사용자에게 진행 파일을 삭제할지 질문
+6. **버전 관리 알림**: `.product-playbook-progress.md`가 처음 생성될 때, 사용자에게 알림: "⚠️ `.product-playbook-progress.md`를 `.gitignore`에 추가하는 것을 권장합니다 — 이 파일에 민감한 제품 전략 정보가 포함될 수 있습니다."
+5. **중단 저장**: 플로우 중 관련 없는 프롬프트가 감지되면 (SKILL.md 플로우 중단 처리 규칙 참조), 현재 단계가 아직 완료되지 않았더라도 진행을 저장합니다. 저장 형식에서 현재 단계에 ✅ 대신 🔶 (진행 중)을 사용하고, 부분적으로 작성된 내용을 보존:
+```
+### S[X]: [단계명] 🔶 (진행 중, 부분 완료)
+[부분적으로 작성된 내용]
+⚠️ 이 단계는 아직 완료되지 않았습니다 — 복구 시 여기서 재개하세요
+```

package/i18n/ko/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 읽기
+────
+최종 산출물 → 1페이지 방향 요약
+```
+
+## 레퍼런스 로딩 지침
+
+각 단계에 진입할 때 해당 레퍼런스 파일을 읽으세요:
+
+| 단계 | 레퍼런스 파일 |
+|------|-------------|
+| S1 | `references/02b-jtbd.md` |
+| S2 | `references/04a-prfaq.md` |
+| S3 | `references/05a-northstar-aha.md` |
+
+## 최종 산출물 형식
+
+**1페이지 방향 요약**: 문제 → 솔루션 → 성공 정의, 빠른 브리핑이나 팀 싱크에 적합한 3파트 구조.
+
+완료 후, `references/rules-end-of-flow.md`에 따라 플로우 종료 규칙을 실행하세요. 퀵 모드에서는 프레젠테이션이 필요한지만 질문 — PRD나 개발 핸드오프 패키지는 제안하지 않습니다 (내용이 충분히 포괄적이지 않으므로).

package/i18n/ko/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.  포지셔닝 재평가 → 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], North Star 지표는 [Y]였습니다. 변경된 것이 있나요? 최신 DAU/MAU와 리텐션 수치는?" — 이전에 수집된 의사결정 이력과 알려진 페인포인트는 재수집 불필요.
+- **컨텍스트 사용 불가 (시나리오 2)**: Context Bootstrap 트리거 (`rules-context.md` 섹션 4, 라운드 1 + 3), 그 다음 아래 표준 S1 데이터 수집 진행.
+- **부분 컨텍스트 (시나리오 3)**: Decision History에서 기능 변경 이력 가져오기 (어떤 모듈이 변경되었고 어떤 리스크가 식별되었는지 파악), 하지만 전체 제품 전략과 지표는 질문 (이전 작업은 기능 확장만 다뤘고 전체적 관점이 부족함).
+
+### S1 표준 안내
+
+> 리비전 모드의 S1은 사용자에게 기존 제품 데이터를 제공하도록 능동적으로 질문합니다: DAU/MAU, 리텐션율, 주요 사용자 피드백, 이전 버전 결정 등. 컨텍스트가 일부 답변을 이미 입력한 경우 재수집이 아닌 확인.
+> S1은 또한 현재 보안 상태를 수집합니다: 기존 인증/인가 메커니즘, 알려진 보안 취약점 또는 기술 부채, 최근 보안 인시던트. 이 정보는 리비전의 리스크 평가와 Pre-mortem에 영향을 미칩니다.
+
+### 빠른 경로
+
+사용자가 S1에서 충분한 데이터를 제공할 때 (사용자 피드백, 지표, 페인포인트 포함), S4-S7 (페인포인트 → 포지셔닝 → HMW → 기회 평가)을 단일 대화 턴에서 작성할 수 있으며, 4번이 아닌 1번의 확인만 필요합니다. 트리거 조건: S3에서 수집된 페인포인트 목록이 이미 명확한 우선순위와 데이터 지원을 가지고 있는 경우. 하드 게이트 규칙은 변경되지 않음 — 각 단계의 산출물은 여전히 완전히 제시되어야 하며; 확인 리듬만 가속됩니다.
+
+## 레퍼런스 로딩 지침
+
+| 단계 | 레퍼런스 파일 |
+|------|-------------|
+| S1-S3 | 외부 레퍼런스 필요 없음 (사용자에게 직접 데이터 제공 안내) |
+| 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`에 따라 플로우 종료 규칙을 실행하세요.