product-playbook 1.0.0

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

@@ -0,0 +1,261 @@
+# Reglas de Importación y Análisis de Documentos
+
+> Se carga cuando el usuario sube un archivo PDF / DOCX / PPTX, o activa `/parse [archivo]`.
+> En el primer uso, cargar `rules-document-tools.md` primero para confirmar que las herramientas están instaladas.
+> Esta regla funciona en conjunto con `rules-file-integration.md` — ese archivo define "cuándo activar," este archivo define "cómo analizar."
+
+---
+
+## Objetivo del Análisis
+
+Convertir cualquier formato de documento de entrada en **Markdown estructurado** para uso en flujos posteriores:
+- Recopilación de contexto S1 del modo Extensión de Funcionalidades / Revisión
+- Baseline del documento fuente para actualización incremental
+- Extracción general de contenido de documentos
+
+---
+
+## Análisis de PDF: Estrategia de Tres Capas + Detección Por Página
+
+### Resumen General
+
+```
+PDF de entrada
+  │
+  ▼
+Extracción de texto por página con pymupdf (costo cero)
+  │
+  ├── Texto de página > 30 caracteres → ✅ Convertir directamente a Markdown (Capa 1)
+  │
+  └── Texto de página ≤ 30 caracteres (en blanco / trazos vectoriales / escaneado)
+        │
+        ├── Por defecto → Análisis semántico con Claude Vision (Capa 2)
+        │
+        └── Vision no disponible / Presupuesto de tokens insuficiente → Tesseract OCR (Capa 3)
+```
+
+### Paso 1: Detección de Tipo Por Página
+
+**Principio clave**: Detectar a nivel de "página", no del documento completo. Un solo PDF puede mezclar páginas de texto digital y páginas de imágenes escaneadas.
+
+```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:
+        # Capa 1: Texto digital, extraer directamente
+        page_results[i] = {"type": "digital", "text": text}
+    else:
+        # Necesita Vision u 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"Análisis PDF: {total_pages} páginas, {digital_count} extraíbles directamente, {vision_count} requieren análisis visual")
+```
+
+### Paso 2: Estrategia para Archivos Grandes
+
+| Condición | Estrategia |
+|-----------|-----------|
+| Todas las páginas son digitales (vision_count = 0) | Extraer todas las páginas directamente, costo cero |
+| vision_count ≤ 20 | Leer todas las páginas que necesitan análisis visual de una vez con Claude Vision |
+| vision_count > 20 | Procesar en lotes (≤ 20 páginas cada uno), fusionar resultados |
+| Total de páginas > 50 y vision_count > 20 | Preguntar al usuario si desea analizar el documento completo o especificar un rango de páginas |
+
+**Prompt de confirmación para archivos grandes (>50 páginas)**:
+
+```
+📄 Este PDF tiene {total_pages} páginas:
+  • {digital_count} páginas se pueden extraer directamente (gratis)
+  • {vision_count} páginas requieren análisis visual (consume tokens de Vision)
+
+Por favor elige:
+  1️⃣ Análisis completo del documento (completo pero consume más tokens)
+  2️⃣ Analizar solo páginas específicas (ingresa rangos de páginas, p.ej. 1-10,15,20-25)
+  3️⃣ Extraer solo páginas directamente extraíbles (omitir páginas escaneadas/vectoriales)
+```
+
+### Paso 3: Capa 1 — Extracción Directa con pymupdf
+
+```python
+def extract_digital_pages(doc, page_results):
+    """Extraer todas las páginas de texto digital"""
+    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)
+```
+
+### Paso 4: Capa 2 — Análisis Semántico con Claude Vision
+
+Para páginas de tipo `needs_vision`, primero renderizar a PNG con pymupdf, luego leer con la herramienta Read de Claude.
+
+**Renderizar a imagen**:
+```python
+def render_pages_to_png(doc, page_indices, dpi=300):
+    """Renderizar páginas especificadas a 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
+```
+
+**Prompt de análisis con Claude Vision**:
+
+Para cada página que requiere análisis visual (o lote), después de leer el PNG con la herramienta Read, convertir usando el siguiente prompt:
+
+```
+Estás leyendo la página {page_num}/{total_pages} de un documento PDF.
+Por favor convierte el contenido de esta página precisamente a formato Markdown.
+
+Reglas estrictas:
+1. Tablas → Tabla Markdown (preservar todas las columnas, filas y alineación)
+2. Encabezados → # / ## / ### correspondiente al nivel original
+3. Listas numeradas → 1. 2. 3. (preservar numeración original)
+4. Viñetas → - o •
+5. Negrita/Cursiva → **negrita** / *cursiva*
+6. Gráficos/Imágenes → > [Gráfico: descripción breve]
+7. Encabezados de página, pies de página, números de página → Ignorar
+8. Números, fechas, nombres, números de cuenta → Deben ser 100% precisos, no adivinar
+9. No agregar contenido que no esté presente en el original
+10. No traducir — preservar el idioma original
+```
+
+> **Por qué esto es mejor que OCR**: Claude entiende la "estructura semántica" de las tablas (qué fila es el encabezado, qué columnas están alineadas), mientras que Tesseract solo puede reconocer caracteres uno por uno e intentar reconstruir tablas con reglas, lo cual frecuentemente falla.
+
+### Paso 5: Capa 3 — Fallback con Tesseract OCR
+
+Usar solo en las siguientes situaciones:
+- El usuario solicita explícitamente conservar tokens
+- Claude Vision no está disponible (limitaciones de API, etc.)
+- Entorno offline
+
+```python
+import subprocess
+from PIL import Image
+
+def ocr_page(png_path, lang="chi_tra+eng"):
+    """Tesseract OCR página individual"""
+    # macOS tesseract puede no leer PNG directamente, convertir a TIFF o usar 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
+```
+
+**Notas sobre Tesseract (de experiencia práctica)**:
+- En macOS, tesseract puede no leer archivos PNG directamente — usar pipe `stdin` o convertir a TIFF primero
+- Resolución recomendada: 300dpi
+- El paquete de idiomas `chi_tra+eng` reconoce tanto chino tradicional como inglés simultáneamente
+- Los resultados de OCR necesitan post-procesamiento: fusionar líneas rotas, reparar estructura de tablas
+
+### Paso 6: Fusionar Todas las Páginas
+
+```python
+def merge_all_pages(digital_md, vision_md_list):
+    """Fusionar el Markdown de todas las páginas en orden de página"""
+    all_pages = {}
+    # páginas digitales
+    for page_num, md in digital_md.items():
+        all_pages[page_num] = md
+    # páginas vision/ocr
+    for page_num, md in vision_md_list.items():
+        all_pages[page_num] = md
+
+    # Ordenar por número de página y fusionar
+    final_md = []
+    for i in sorted(all_pages.keys()):
+        final_md.append(all_pages[i])
+
+    return "\n\n---\n\n".join(final_md)
+```
+
+### Paso 7: Output y Notificación al Usuario
+
+```
+📄 Análisis de PDF completado:
+  • Total de páginas: {total_pages}
+  • Extracción directa: {digital_count} páginas (pymupdf)
+  • Análisis visual: {vision_count} páginas (Claude Vision)
+  • Output: {output_path} (Markdown, {word_count} palabras)
+```
+
+---
+
+## Análisis de DOCX
+
+```bash
+pandoc "{input_path}" -t markdown -o "/tmp/parsed-{timestamp}.md" --wrap=none
+```
+
+**Post-procesamiento**:
+- Eliminar líneas en blanco excesivas generadas por Pandoc
+- Verificar que el formato de tablas sea correcto
+
+---
+
+## Análisis de PPTX
+
+```bash
+pandoc "{input_path}" -t markdown -o "/tmp/parsed-{timestamp}.md" --wrap=none
+```
+
+> Pandoc convierte cada diapositiva en una sección con encabezado `##`.
+
+---
+
+## Análisis de HTML
+
+```bash
+pandoc "{input_path}" -f html -t markdown -o "/tmp/parsed-{timestamp}.md" --wrap=none
+```
+
+---
+
+## Análisis de Imágenes
+
+Usar directamente la herramienta Read de Claude para leer la imagen, luego convertir a Markdown usando el prompt de análisis de Vision.
+
+---
+
+## Coordinación con rules-file-integration.md
+
+Cuando `rules-file-integration.md` detecta los siguientes escenarios, se carga esta regla:
+
+| Escenario | Acción |
+|-----------|--------|
+| El usuario sube un PDF durante Extensión de Funcionalidades S1 | Cargar esta regla → Analizar PDF → Extraer contexto del sistema existente |
+| El usuario sube un PRD antiguo durante Revisión S1 | Cargar esta regla → Analizar PDF → Usar como baseline de revisión |
+| El usuario usa el comando `/parse` | Cargar esta regla → Analizar archivo especificado → Output en Markdown |
+| El usuario sube un reporte de mercado en PDF | Cargar esta regla → Extraer información clave → Integrar en el paso correspondiente |
+
+### Identificación de Documento Fuente
+
+Después de completar el análisis, si el archivo se identifica como un "documento fuente" (PRD, especificación, etc.), marcarlo automáticamente:
+
+```
+📎 Documento fuente detectado — la salida final será una actualización incremental basada en este archivo.
+  Estructura del documento: {section_count} secciones, {table_count} tablas
+  Convenciones de formato: [características de formato identificadas]
+```
+
+La estructura del documento se registra para uso de `rules-export-document.md` durante la salida final.

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

@@ -0,0 +1,14 @@
+# 🏢 Ajustes de Diferenciación B2B / B2C
+
+> Se carga después de confirmar el tipo de producto. Claude aplica automáticamente los siguientes ajustes dentro de cada framework.
+
+| Framework | Ajustes B2C | Ajustes B2B |
+|-----------|------------|------------|
+| **Persona** | Segmentar por motivaciones/hábitos personales | Distinguir entre "tomador de decisión de compra" y "usuario final real" como dos tipos de Persona; agregar campos "tamaño de organización" y "proceso de adquisición" |
+| **JTBD** | Enfoque en jobs emocionales y sociales personales | Agregar "jobs a nivel organizacional": ¿Qué objetivo ayuda a lograr a la empresa? ¿Qué trabajo realiza el individuo dentro de la organización? |
+| **Evaluación de PMF** | Principalmente basada en DAU/MAU, tasa de retención, Sean Ellis Score | Principalmente basada en "clientes que pagan + tasa de expansión + NPS"; Nivel 1 = 3-5 clientes que pagan |
+| **Aha Moment** | Valor central experimentado durante el primer uso | Puede no surgir hasta el onboarding/período de prueba; diseñar una métrica "Time-to-Value" |
+| **MVP** | Puede ser un producto ligero completo | Puede necesitar ser un Piloto (un despliegue personalizado para un cliente específico) |
+| **GTM** | Principalmente crecimiento liderado por producto (PLG) o impulsado por comunidad | Principalmente impulsado por ventas o por canal de aliados |
+| **Precios** | Freemium / Suscripción / Basado en uso | Contrato anual / Por asiento / Basado en uso / Cotización personalizada |
+| **North Star** | Actividad de usuarios o conteo de completación de acción central | ARR, Net Revenue Retention, Cuentas Activas |

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

@@ -0,0 +1,60 @@
+# 🔁 Persistencia de Progreso y Recuperación de Interrupciones
+
+> Se carga cuando el usuario dice "pausar," "guardar," o cuando el skill verifica progreso al inicio.
+
+## Formato del Archivo de Progreso
+
+Después de completar cada paso, crear o actualizar `.product-playbook-progress.md` en el directorio del proyecto:
+
+```
+# Guardado de Progreso de Product Playbook
+
+- Modo: [Modo Rápido / Modo Completo / ...]
+- Tipo de producto: [B2C / B2B / ...]
+- Descripción del producto: [Descripción del producto del usuario]
+- Progreso actual: S[X] / S[Y]
+- Última actualización: [timestamp]
+
+## Pasos Completados
+
+### S1: [Nombre del paso] ✅
+[Output central de este paso — retener suficiente detalle para no necesitar rehacerlo al recuperar]
+
+### S2: [Nombre del paso] ✅
+[Igual que arriba]
+
+## Pasos Pendientes
+- S3: [Nombre del paso]
+- S4: [Nombre del paso]
+- ...
+```
+
+### Ejemplo de Modo Extensión de Funcionalidad
+```markdown
+Modo: Extensión de Funcionalidad
+Paso: S2/S4
+S1: Problema + contexto del sistema existente ✅
+S2: Tres soluciones paralelas + recomendación de IA ▶️
+S3: Evaluación de riesgos ⬜
+S4: Alcance de ejecución ⬜
+```
+
+## Reglas de Activación
+
+1. **Auto-guardado**: Después de completar cada paso y ser confirmado por el usuario, actualizar inmediatamente el archivo de progreso
+2. **Verificar al inicio**: Cuando el skill se activa, primero verificar si `.product-playbook-progress.md` existe. Si existe, mostrar:
+```
+Progreso no terminado de planificación de producto detectado ([nombre del modo], S[X]/S[Y]):
+  1️⃣ Continuar — Retomar desde S[X]
+  2️⃣ Empezar de nuevo — Limpiar progreso anterior y comenzar desde cero
+(Ingresa 1 o 2)
+```
+3. **Comando de pausa**: Cuando el usuario dice "pausar," "hacer otra cosa primero," o "guardar," confirmar que el archivo de progreso ha sido actualizado y responder: "Progreso guardado en .product-playbook-progress.md (S[X]/S[Y]). Será detectado automáticamente la próxima vez que inicies el skill en este proyecto."
+4. **Limpieza al completar**: Después de que todo el flujo esté completo y los documentos finales producidos, preguntar al usuario si desea eliminar el archivo de progreso
+6. **Recordatorio de control de versiones**: Cuando `.product-playbook-progress.md` se crea por primera vez, recordar al usuario: "⚠️ Recomendamos agregar `.product-playbook-progress.md` a `.gitignore` — este archivo puede contener información sensible de estrategia de producto."
+5. **Guardado de interrupción**: Cuando se detecta un prompt no relacionado durante el flujo (ver reglas de manejo de interrupciones en SKILL.md), guardar progreso incluso si el paso actual no está completo. Usar 🔶 (en progreso) en lugar de ✅ para el paso actual en el formato de guardado, y preservar el contenido parcialmente producido:
+```
+### S[X]: [Nombre del paso] 🔶 (en progreso, parcialmente completado)
+[Contenido parcialmente producido]
+⚠️ Este paso no está completo — retomar desde aquí al recuperar
+```

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

@@ -0,0 +1,29 @@
+# 🚀 Secuencia de Pasos del Modo Rápido (3 Pasos + Output Final)
+
+> Este archivo es la definición autoritativa de pasos para el Modo Rápido. Cargado por el despachador central de SKILL.md.
+
+## Secuencia de Pasos
+
+```
+S1. Declaración JTBD → Leer references/02b-jtbd.md
+S2. PR-FAQ → Leer references/04a-prfaq.md
+S3. North Star Metric + Aha Moment → Leer references/05a-northstar-aha.md
+────
+Output Final → Resumen de dirección de una página
+```
+
+## Instrucciones de Carga de Referencias
+
+Al entrar a cada paso, lee el archivo de referencia correspondiente:
+
+| Paso | Archivo de Referencia |
+|------|----------------------|
+| S1 | `references/02b-jtbd.md` |
+| S2 | `references/04a-prfaq.md` |
+| S3 | `references/05a-northstar-aha.md` |
+
+## Formato del Output Final
+
+**Resumen de dirección de una página**: Problema → Solución → Definición de Éxito, una estructura de tres partes adecuada para briefings rápidos o sincronizaciones de equipo.
+
+Al completar, sigue `references/rules-end-of-flow.md` para ejecutar las reglas de fin de flujo. El Modo Rápido solo pregunta si se necesita una presentación — no ofrece PRD ni paquetes de handoff de desarrollo (el contenido no es lo suficientemente comprehensivo).

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

@@ -0,0 +1,64 @@
+# 🔄 Secuencia de Pasos del Modo Revisión (12 Pasos + Output Final)
+
+> Este archivo es la definición autoritativa de pasos para el Modo Revisión. Cargado por el despachador central de SKILL.md.
+
+## Secuencia de Pasos
+
+```
+Fase 0: Análisis del Estado Actual
+  S1.  Revisión del producto existente (resumen de datos de usuario + métricas centrales + problemas conocidos + estado de seguridad)
+  S2.  Re-examinar JTBD de usuarios existentes (¿qué jobs se están haciendo bien? ¿cuáles no?)
+
+Fase 1: Convergencia del Problema
+  S3.  Recopilación de puntos de dolor de usuario (análisis de retención/churn + síntesis de feedback de usuarios + datos de comportamiento)
+  S4.  Tabla de resumen de puntos de dolor → cargar references/03-define.md → 2.1
+  S5.  Re-evaluación de posicionamiento → cargar references/03-define.md → 2.2 (enfoque: ¿el posicionamiento necesita ajuste?)
+  S6.  Reformulación de preguntas HMW → cargar references/03-define.md → 2.3
+  S7.  Tabla de evaluación de oportunidades → cargar references/03-define.md → 2.4
+
+Fase 2: Diseño de Solución
+  S8.  PR-FAQ → cargar references/04a-prfaq.md (describir la experiencia post-revisión)
+  S9.  Pre-mortem → cargar references/04b-solutions.md → 3.3
+  S10. Alcance MVP + Lista de No Hacer → cargar references/04c-mvp.md (enfoque: qué cambiar / qué no cambiar)
+
+Fase 3: Validación
+  S11. North Star + Aha Moment → cargar references/05a-northstar-aha.md (comparar métricas pre- vs. post-revisión)
+  S12. Plan de validación de hipótesis → cargar references/05c-validation-spec.md
+────
+Output Final → Resumen de spec de producto (edición de revisión)
+```
+
+### Pre-paso S1: Carga de Contexto de Producto
+
+Antes de entrar a S1, cargar `references/rules-context.md` y verificar `.product-context.md`:
+
+- **Contexto completo disponible (Escenario 1)**: Auto-rellenar nivel de PMF, North Star, puntos de dolor conocidos, estado de seguridad, y las 3 entradas más recientes del Historial de Decisiones. La guía de S1 cambia a **modo delta**: "La última vez que evaluamos, tu nivel de PMF era [X] y tu North Star metric era [Y]. ¿Ha cambiado algo? ¿Cuáles son los últimos números de DAU/MAU y retención?" — El historial de decisiones y puntos de dolor recopilados previamente no necesitan re-recopilarse.
+- **Sin contexto disponible (Escenario 2)**: Activar Context Bootstrap (`rules-context.md` Sección 4, Ronda 1 + 3), luego proceder a la recopilación estándar de datos de S1 abajo.
+- **Contexto parcial (Escenario 3)**: Traer historial de cambios de features del Historial de Decisiones (saber qué módulos fueron cambiados y qué riesgos se identificaron), pero preguntar sobre estrategia general del producto y métricas (el trabajo anterior solo cubrió expansión de features y carece de una visión holística).
+
+### Guía Estándar de S1
+
+> El S1 del Modo Revisión pregunta proactivamente al usuario que proporcione datos del producto existente: DAU/MAU, tasas de retención, feedback clave de usuarios, decisiones de versiones anteriores, etc. Si el contexto ya pre-llenó algunas respuestas, confirmar en lugar de re-recopilar.
+> S1 también recopila el estado de seguridad actual: mecanismos de autenticación/autorización existentes, vulnerabilidades de seguridad conocidas o deuda técnica, incidentes de seguridad recientes. Esta información afecta la evaluación de riesgos de la revisión y el Pre-mortem.
+
+### Ruta Rápida
+
+Cuando el usuario proporciona datos suficientes en S1 (incluyendo feedback de usuarios, métricas y puntos de dolor), S4–S7 (puntos de dolor → posicionamiento → HMW → evaluación de oportunidades) pueden producirse en un solo turno de conversación, requiriendo solo una confirmación en lugar de cuatro. Condición de activación: la lista de puntos de dolor recopilada en S3 ya tiene priorización clara y soporte de datos. Las reglas de Hard Gate permanecen sin cambios — el output de cada paso debe presentarse completamente; solo la cadencia de confirmación se acelera.
+
+## Instrucciones de Carga de Referencias
+
+| Paso | Archivo de Referencia |
+|------|----------------------|
+| S1–S3 | No se necesita referencia externa (guiar al usuario para proporcionar datos directamente) |
+| 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 + Output Final | `references/05c-validation-spec.md` |
+
+## Formato del Output Final
+
+**Resumen de Spec de Producto de Revisión**: Comparación antes/después + qué cambiar / qué no cambiar + métricas de éxito
+
+Al completar, ejecuta reglas de fin de flujo según `references/rules-end-of-flow.md`.