adamjali/explain

<essential_principles>

Cómo Funciona Esta Habilidad

Dos modos, enrutados automáticamente según el tema (ver tabla de enrutamiento):

• Modo A — Repo / concepto / docs (la ruta barata): investigación → clonar (si es repo) → explorar → sintetizar → generar salida. Los agentes paralelos sueltos están bien.
• Modo B — Producto web en vivo / competidor / producto de datos / algoritmo / panorama (el paquete completo): explorar → confirmar → reconocimiento profundo orquestado por Workflow → captura con navegador real → ingeniería inversa a código validado → sintetizar. Lee @references/competitor-teardown.md y síguelo.

Enrutamiento por tipo de tema

Tema	Señal	Modo	Columna vertebral
Repositorio de GitHub	github.com	A	clon + agentes Explore
Concepto / tecnología	sin URL	A	agentes de investigación
Documentación / sitio estático	URL, informativo	A	investigador + WebFetch
Producto en vivo / app / SaaS / competidor	La URL es un producto; "competidor/desglose/vs nosotros/cómo lo hacen"	B	navegador + Workflow + esquema por tema
Calculadora / estimador / predictor / precios / ranking	una fórmula/algoritmo a descifrar	B	cuadrícula de sondeo en vivo → implementación de referencia ejecutable → validar
Panorama completo	"encuentra todos los demás / todos en este espacio"	B	descubrimiento de espacio de nombres → desglose del conjunto SÍ

Desempate: si una URL es TANTO un producto como tiene documentación, el valor predeterminado es B: la pasada de exploración es barata y se degrada a A si no hay nada que desglosar.

Reglas de Ejecución

1. Herramienta adecuada para la escala: Modo A = llamadas paralelas a Task/Agent. Modo B = la herramienta Workflow (pipelines, esquemas de salida estructurada, reanudación) una vez que hay 3+ temas o trabajo multifase.
2. Fundamentar, luego confirmar: el Modo B realiza una pasada de exploración barata + una puerta de confirmación (alcance + límite de reconocimiento + navegador) antes de la inmersión costosa, a menos que el usuario ya haya dicho "todo el paquete / a fondo / todo".
3. Ingeniería inversa a código ejecutable y validado para cualquier calculadora/algoritmo; comparar con la fuente de verdad autorizada, no con la afirmación del competidor.
4. Énfasis visual: cada concepto importante recibe un diagrama o tabla.
5. Salida dual: mostrar el resumen ejecutivo + el índice de archivos en la conversación; guardar el conjunto completo de documentos en ~/.claude/explanations/<fecha>_<slug>/.
6. Resiliencia: la investigación pesada del Modo B se ejecuta como un Workflow en segundo plano; persistir artefactos de forma incremental; reanudar (resumeFromRunId) ante un corte.
7. Limpieza: ofrecer eliminar los repositorios clonados / archivos guardados al finalizar. </essential_principles>

<scope_boundary>

Límite de reconocimiento del Modo B (crítico: léelo antes de cualquier sondeo en vivo)

El reconocimiento competitivo es legal y normal en superficies PÚBLICAS. Reglas completas en @references/competitor-teardown.md. Los invariantes:

• PERMITIDO: páginas/activos públicos, OpenAPI /docs públicos, paquetes JS públicos, una cuadrícula MODESTA y educada (~15-40, tasa baja) de solicitudes de nivel de usuario normal a puntos finales públicos para derivar una fórmula, huella digital de encabezados, WHOIS/DNS.
• NUNCA: vencer CAPTCHA / desafíos de bots, evitar la autenticación, cosechar conjuntos de datos completos (solo muestra), pruebas de estrés, o invocar puntos finales de administración/mutación/destrucción (DOCUMENTARLOS, no llamarlos). Observar exposiciones; nunca explotarlas. Nunca enviar datos reales del usuario en un formulario de la competencia. Si no estás seguro, no lo hagas, y explica por qué. </scope_boundary>

<intake_gate>

<no_context_handler> SI $ARGUMENTS está vacío: → Usar AskUserQuestion:

• encabezado: "Explicar"
• pregunta: "¿Qué te gustaría que explicara?"
• opciones:
  • "Repositorio de GitHub" - Analizar un código base de GitHub
  • "Sitio web o documentación" - Comprender un sitio web, documentación o API
  • "Competidor / producto en vivo / panorama" - Desglosar un producto en vivo, aplicar ingeniería inversa a una calculadora o mapear un espacio competitivo completo (Modo B)
  • "Concepto o tecnología" - Explicar un concepto, marco de trabajo o herramienta

Luego proceder a context_analysis. </no_context_handler>

<context_analysis> Analizar $ARGUMENTS para extraer:

• Tipo: Repositorio de GitHub, sitio web, concepto u otro
• URL/Tema: La cosa específica a explicar
• Objetivo implícito: ¿Aprender a usar? ¿Evaluar? ¿Entender la arquitectura? ¿Contribuir?

Detectar el tipo automáticamente:

• Contiene github.com → Repositorio de GitHub (Modo A)
• Señales del Modo B → "competidor", "desglose", "ingeniería inversa", "vs nosotros", "cómo lo hacen", "encuentra todos los demás", o una URL que es un producto/app/calculadora → Modo B
• Contiene http (informativo/docs) → Sitio web (Modo A)
• De lo contrario → Concepto (Modo A) </context_analysis>

<initial_questions> Usar AskUserQuestion solo para lagunas genuinas (máximo 2-3 preguntas):

Objetivo (si no está claro):

• "¿Cuál es tu objetivo?" con opciones:
  • "Entender cómo funciona" - Arquitectura, flujo, implementación
  • "Evaluar para adopción" - Pros/contras, alternativas, adecuación para mi caso de uso
  • "Aprender a usarlo" - Configuración, API, primeros pasos
  • "Aprender a contribuir" - Estructura del código base, flujo de trabajo de desarrollo

Enfoque (si el tema es amplio):

• "¿Algún enfoque específico?" con opciones:
  • "Todo" - Análisis completo exhaustivo
  • "Solo la arquitectura" - Estructura de alto nivel y patrones
  • "Característica específica" - Un aspecto en particular (especificar)

Antecedentes (si es útil):

• "¿Tu nivel técnico?" con opciones:
  • "No técnico" - Explicar desde primeros principios con analogías
  • "Técnico pero nuevo en este dominio" - Omitir lo básico, centrarse en lo específico
  • "Experto" - Técnico profundo, asumir conocimiento </initial_questions>

<decision_gate> Después de las respuestas, usar AskUserQuestion (Modo A):

• pregunta: "¿Listo para comenzar la inmersión profunda?"
• opciones:
  • "Sí, adelante" - Comenzar el análisis multifase
  • "Más preguntas primero" - Tengo aclaraciones
  • "Déjame añadir contexto" - Quiero agregar detalles

El Modo B reemplaza esta puerta con B2 (instantánea + alcance + límite de reconocimiento + adelante/profundidad/navegador) — no preguntar ambas; B2 es la única puerta autorizada para desgloses. </decision_gate>

</intake_gate>

Selección de modo

Ejecutar <intake_gate>, luego enrutar según la tabla de tipo de tema. Modo B (producto en vivo / competidor / producto de datos / calculadora / panorama) → cargar @references/competitor-teardown.md y seguir su flujo de exploración → confirmación → profundidad → síntesis (esqueleto a continuación). Modo A (repo / concepto / docs) → Fases 1-7 a continuación.

Modo B — Desglose de producto en vivo / competidor / producto de datos

Libro de jugadas completo en references/competitor-teardown.md. Esqueleto:

• B0 Fundamentar: verificar memoria + ~/.claude/explanations/ para análisis previo; extender, no rehacer.
• B1 Explorar: un agente de reconocimiento pasivo ligero por objetivo (WebFetch + encabezados + WebSearch) → instantánea fundamentada + qué necesita un navegador.
• B2 Puerta de confirmación: presentar instantánea + alcance + el límite de reconocimiento (<scope_boundary>); AskUserQuestion para adelante/profundidad/navegador — omitir solo si el usuario ya dijo "a fondo / todo el paquete".
• B3 Reconocimiento profundo (Workflow): un agente estructurado por tema, todos compartiendo el esquema por tema (en la referencia). pipeline() por defecto; dividir salidas grandes a disco.
• B4 Navegador (Claude-in-Chrome): capturar red al cargar, renderizar SPAs, probar estimadores en vivo a través de una cuadrícula de entrada, encabezados de seguridad, copia de paywall/auth — dentro del límite (sin bypass de CAPTCHA/auth, sin puntos finales mutantes, nunca enviar los datos del usuario). Persistir las capturas a medida que avanzas.
• B5 Ingeniería inversa: cada calculadora → implementación de referencia TypeScript ejecutable → validar vs la cuadrícula en vivo → comparar con la fuente de verdad autorizada.
• B6 Espacio de nombres (si "¿algún otro?"): DNS+curl+búsqueda de dominios candidatos, clasificar, encontrar clústeres de operadores, marcar dominios de compra defensiva, desglosar solo el conjunto SÍ genuinamente distinto.
• B7 Sintetizar: agentes de síntesis en abanico → DETAILED-<slug>.md ×N + ESTIMATORS.md + COMPARISON.md (incl. una sección de integridad de datos + clúster de operadores) + REPLICATION-BLUEPRINT.md + ARCHITECTURE.md + NAMESPACE.md + SOURCES-*.md + SUMMARY.md (resumen ejecutivo + índice de archivos). Luego Fase 7 de salida/limpieza.

---

Modo A — Repo / concepto / docs

Fase 1: Investigación Web en Paralelo (5 agentes de investigación)

Generar TODOS en un mensaje:

Task(subagent_type="general-purpose", prompt="Investigar [TEMA]: ¿Qué es? ¿Quién lo hizo? ¿Cuándo? ¿Por qué?")
Task(subagent_type="general-purpose", prompt="Investigar [TEMA]: Stack técnico, arquitectura, tecnologías clave")
Task(subagent_type="general-purpose", prompt="Investigar [TEMA]: Artículos, reseñas, discusiones comunitarias, opiniones")
Task(subagent_type="general-purpose", prompt="Investigar [TEMA]: Alternativas, comparaciones, cuándo usar vs no usar")
Task(subagent_type="general-purpose", prompt="Investigar [TEMA]: Documentación, tutoriales, guías de inicio")

Fase 2: Clonar Repositorio (si es GitHub)

REPO_DIR=~/.claude/explanations/$(date +%Y%m%d_%H%M%S)_$(basename [URL] .git)
git clone [URL] $REPO_DIR
cd $REPO_DIR

Fase 3: Exploración Paralela del Código Base (6 agentes Explore)

Generar TODOS en un mensaje con minuciosidad="muy minucioso":

Task(subagent_type="Explore", prompt="Arquitectura: Estructura general, módulos, cómo se relacionan")
Task(subagent_type="Explore", prompt="Puntos de entrada: Archivos principales, CLI, endpoints de API, cómo inicia")
Task(subagent_type="Explore", prompt="Lógica central: Algoritmos clave, patrones, abstracciones")
Task(subagent_type="Explore", prompt="Configuración: Ajustes, entorno, puntos de extensibilidad")
Task(subagent_type="Explore", prompt="Dependencias: Paquetes clave, integraciones, servicios externos")
Task(subagent_type="Explore", prompt="Pruebas y calidad: Patrones de prueba, cobertura, CI/CD")

Fase 4: Contexto Paralelo de Claude Code (2-3 agentes de propósito general)

Si es relevante para Claude/AI/agentes:

Task(subagent_type="general-purpose", prompt="Explicar conceptos relevantes de Claude Code para entender esto")
Task(subagent_type="general-purpose", prompt="Comparar con herramientas/SDK de Claude si aplica")

Fase 5: Punto de Control Intermedio (si es complejo)

Usar AskUserQuestion si los hallazgos revelan complejidad:

• "Encontré [X]. ¿Quieres que me centre en algo específico?"
• Opciones basadas en descubrimientos

Fase 6: Síntesis

Combinar todos los hallazgos en una explicación completa con:

1. Analogía inicial (comparación no técnica)
2. Qué es (1-2 frases)
3. Diagrama de arquitectura (ASCII)
4. Cómo funciona (paso a paso con diagramas)
5. Tabla de componentes clave (nombre, propósito, cómo funciona)
6. Qué tiene de especial (diferenciadores)
7. Lista de capacidades (lo que puede hacer)
8. Tabla comparativa (vs alternativas)
9. Inmersión técnica (detalles de implementación)
10. Trampas y consideraciones

Fase 7: Salida

Mostrar en la conversación

Explicación completa formateada con todos los elementos visuales.

Guardar en archivos

OUTPUT_DIR=~/.claude/explanations/$(date +%Y%m%d_%H%M%S)_[tema-slug]
mkdir -p $OUTPUT_DIR

# Guardar archivos:
# $OUTPUT_DIR/SUMMARY.md - Referencia rápida (versión de 30 segundos)
# $OUTPUT_DIR/DETAILED.md - Análisis completo
# $OUTPUT_DIR/ARCHITECTURE.md - Todos los diagramas
# $OUTPUT_DIR/COMPARISON.md - Análisis de alternativas

Seguimiento

Después de mostrar, preguntar:

• "¿Qué aspecto te gustaría explorar más a fondo?"
• "¿Alguna pregunta sobre lo que expliqué?"
• Fomentar el seguimiento

Limpieza

Usar AskUserQuestion para la limpieza (combinar si ambos aplican):

Si se clonó un repo:

• pregunta: "¿Eliminar el repositorio clonado?"
• opciones:
  • "Sí, eliminarlo" - Eliminar $REPO_DIR automáticamente
  • "No, conservarlo" - Mostrar ruta: "Repo conservado en: $REPO_DIR"

Si sí: rm -rf $REPO_DIR Si no: Mostrar ruta para acceso manual

Siempre (archivos de explicación):

• pregunta: "¿Eliminar los archivos de explicación guardados?"
• opciones:
  • "Sí, eliminarlos" - Eliminar $OUTPUT_DIR automáticamente
  • "No, conservarlos" - Mostrar ruta: "Explicaciones guardadas en: $OUTPUT_DIR"

Si sí: rm -rf $OUTPUT_DIR Si no: Mostrar ruta para acceso manual

Pregunta combinada (si hay tanto repo como archivos):

• pregunta: "Análisis completo. ¿Qué te gustaría limpiar?"
• opciones:
  • "Eliminar tanto el repo como los archivos de explicación"
  • "Eliminar solo el repo, conservar las explicaciones"
  • "Eliminar solo las explicaciones, conservar el repo"
  • "Conservar todo"

Ejecutar eliminaciones según la selección, mostrar rutas para lo que se conserve.

<visual_formats>

Formatos de Diagrama Estándar

Arquitectura:

┌─────────────┐     ┌─────────────┐
│  Componente  │────►│  Componente  │
└─────────────┘     └─────────────┘

Flujo:

INICIO → Paso 1 → Paso 2 → ¿Decisión?
                            ├─ Sí → Ruta A
                            └─ No  → Ruta B

Tabla comparativa:

| Aspecto      | Opción A | Opción B | Ganador |
|-------------|----------|----------|--------|
| Velocidad   | Rápido   | Lento    | A      |

Desglose de componentes:

┌──────────────────────────────────────┐
│           Nombre del Sistema         │
├──────────────────────────────────────┤
│ ┌────────┐ ┌────────┐ ┌────────┐    │
│ │Módulo A│ │Módulo B│ │Módulo C│    │
│ └───┬────┘ └───┬────┘ └───┬────┘    │
│     └──────────┴──────────┘         │
│              Capa Compartida         │
└──────────────────────────────────────┘

</visual_formats>

<success_criteria> Ambos modos:

• Hizo preguntas aclaratorias / fundamentó antes de comenzar; enrutó al modo correcto
• Produjo diagramas visuales para cada concepto importante; incluyó profundidad técnica recreable
• Mostró el resumen ejecutivo en la conversación Y guardó el conjunto de documentos en archivos
• Ofreció seguimiento + limpieza; respetó la elección de conservar/eliminar del usuario

Modo B (producto en vivo / competidor / producto de datos / panorama) también:

• Realizó una pasada de exploración + puerta de confirmación (o respetó un "a fondo" explícito) y declaró el límite de reconocimiento
• Se mantuvo estrictamente dentro del límite: sin bypass de CAPTCHA/auth, sin cosecha masiva, sin llamar a puntos finales mutantes/de administración; nunca envió los datos del usuario; las exposiciones se observaron, no se explotaron
• Usó la herramienta Workflow con un esquema compartido por tema una vez que hubo 3+ temas/fases múltiples; persistió artefactos; resiliente a cortes (reanudar)
• Probó en vivo cada calculadora y entregó una implementación de referencia ejecutable validada N/N contra las salidas observadas, comparada con la fuente de verdad autorizada
• Para paisajes: descubrió el espacio de nombres completo, clasificó cada uno, encontró clústeres de operadores, marcó dominios de compra defensiva, desglosó solo los distintos
• La síntesis incluye una sección de integridad de datos + un análisis de clúster de operadores + un mapa de espacio de nombres + un plano de replicación; "suficiente para competir" </success_criteria>