jmdevilleros/niche-map

Mapa de nichos: brechas en un espacio conceptual

Esta habilidad encuentra brechas bien fundamentadas en un dominio. Convierte un panorama difuso en una tabla de elementos reales × dimensiones explícitas, busca combinaciones y zonas que nadie ocupa, traduce esas brechas en ideas concretas y verifica que no sean espejismos.

Principio rector. Los números organizan el juicio; no lo reemplazan. Los códigos son decisiones del analista, por lo que el espacio refleja tanto la rúbrica como el mercado. Por eso cada brecha propuesta debe superar una verificación de fiabilidad en los códigos (paso 2b) y una validación externa (paso 6).

Herramientas en este repositorio

Archivo	Función
niche_core.py	Pasos 3-4: codificación, clústeres, PCA, UMAP, brechas triples, brechas de densidad, vecinos candidatos, oferta vs demanda, figuras
recode_check.py	Paso 2b: muestra de recodificación ciega y acuerdo por dimensión (kappa de Cohen)
md_to_pdf.py	Paso 7: informe Markdown a PDF
templates/report_template.md	Paso 7: esqueleto del informe
examples/	Conjunto de datos sintético y ficticio para probar el pipeline de principio a fin

---

0. Entradas y preguntas de alcance

Obtén estas respuestas antes de comenzar. Si falta alguna, pregunta una vez, en un solo bloque.

Entrada	Pregunta	Por qué es importante
Tema y límite	¿Qué cuenta como un elemento? (ej. "herramientas cuyo valor central es X")	Evita categorías mixtas y artefactos de brecha.
N	¿Cuántos elementos? (por defecto 80-100; mínimo útil ≈ 50)	Con N < 50 los recuentos triples son ruido.
Criterios de inclusión	Recepción mínima, disponibilidad, plataforma, idioma, fecha	Se aplica en el paso 1 y se documenta.
Usuario objetivo	¿Quién construirá o comprará lo que resulte?	Base de la puntuación de ajuste y de target_filter.
Restricciones	Presupuesto, horas, habilidades, canal de ventas, temas excluidos	Se convierten en target_filter y el criterio de ajuste.
Entregable	Idioma, moneda (y fuente del tipo de cambio), formato	Por defecto: PDF con ranking, tarjetas de nicho, mapas y la tabla completa del corpus con enlaces.

1. Corpus: N elementos reales y verificados

1. Semilla amplia. Recolecta alrededor de 1.3 × N candidatos de fuentes variadas: tiendas o directorios del dominio, listas "mejores de", búsquedas "alternativa a X" y lanzamientos recientes de larga cola (sitios de lanzamiento, directorios de nicho, registros de código abierto). Si solo entran productos famosos, más tarde aparecerán brechas falsas.
2. Verificación de existencia por elemento. Cada elemento necesita una URL que resuelva: página de tienda, página de precios o repositorio. Registra el estado HTTP, la URL final y la fecha. Si un sitio bloquea bots (403), verifica la raíz del dominio o usa un navegador; un bloqueo no significa que el elemento no exista.
3. Señal de recepción. Registra una o más señales públicas (calificación de tienda y número de reseñas, votos de sitio de lanzamiento, estrellas de repositorio, instalaciones, premios) y declara la fuente y cobertura de cada una. No descartes un elemento solo porque no tenga señal. Si la recepción es un criterio de inclusión, aplícalo con un umbral explícito.
4. Desduplica variantes, renombramientos, ediciones y SKU regionales. Mantén el nombre canónico y los enlaces.
5. Excluye por límite los elementos que no cumplen los criterios de inclusión, y enuméralos en el informe con el motivo.
6. Verificaciones de sesgo del corpus (escribe las respuestas en el informe):
   • Proporción de elementos de la larga cola (ej. lanzados en los últimos 24 meses, o por debajo de la señal de recepción mediana). Si es inferior a ~20 %, muestrea más elementos de larga cola.
   • Concentración de fuentes: ninguna fuente debe contribuir más de ~40 % de los elementos.
   • Sesgo de plataforma o idioma en relación con el límite declarado.
   • Cobertura de señales por fuente (algunas fuentes sobrerrepresentan ciertos tipos de usuarios, ej. herramientas de desarrollador en sitios de alojamiento de código).

Salida: items.csv, una fila por elemento con columnas de identificación y enlace, más un JSON sin procesar de la verificación.

2. Dimensiones, escalas y rúbrica de codificación

1. Deriva 8-15 dimensiones leyendo una muestra de unos 20 elementos. Divídelas en dos tipos:
   • Dimensiones conceptuales dicen qué es el elemento: verbo o acción, entrada, salida, desencadenante, dominio o tema, usuario, estética. Las brechas se buscan con estas (gap_dims).
   • Dimensiones de atributo dicen cómo se construye o vende: complejidad, amplitud, autoservicio, modelo de precios, nivel de precio. Filtran y puntúan. Si se usan en la búsqueda de brechas, producen brechas "meta" como "desencadenado por evento + sin IA + alta complejidad".
2. Escalas. Categorías nominales con 3-14 valores mutuamente excluyentes, cada uno con una etiqueta legible, u ordinales cortos (0-1, 0-2, 1-3) con anclas descritas.
3. Rúbrica escrita: una línea por valor con una definición y un ejemplo, más las reglas de decisión a continuación. Va en el apéndice del informe y es el único material que recibe el segundo codificador en el paso 2b.
   • Codifica la estructura lógica, no la representación. Para dimensiones espaciales o estructurales, codifica cómo el usuario realmente interactúa o razona sobre la cosa, no cómo se ve (ej. un producto renderizado en 3D usado en un plano plano no es "3D").
   • Orden de precedencia para valores superpuestos. Cuando una escala nominal describe algo perceptual o estilístico (apariencia, tono, estilo), los valores se superponen. Da un orden de decisión explícito ("si A aplica, codifica A; si no, si B..."), o fusiona valores que los codificadores no puedan distinguir.
   • Anclas medibles para ordinales. Las anclas como duración, tamaño o esfuerzo deben decir cómo medirlas y de qué fuente (ej. "sesión típica según la descripción de la tienda o observada en un video de demostración; para elementos basados en niveles, un nivel"). Si no se puede observar, codifica el caso modal y márcalo.
   • Codifica el modo principal. Si un elemento es ambiguo, codifica su modo principal y anota la duda en una columna notes.
4. Pesos. Por defecto 1.0. Aumenta las dimensiones conceptuales centrales (ej. verbo a 1.2), reduce las periféricas (ej. modelo de precios a 0.4). Justifica cada peso.
5. Verificaciones estructurales:
   • Ninguna categoría con menos de 2 elementos; fusiona o elimínala (niche_core.py advierte).
   • Tablas cruzadas para detectar dimensiones redundantes (correlación ≈ 1): elimina o fusiona una de ellas.
6. Reconoce los límites: los códigos son juicios.

Salida: el CSV de elementos × dimensiones y config.json con escalas, pesos y reglas.

2b. Verificación de recodificación ciega (obligatorio)

Propósito: medir si la rúbrica, no la memoria del codificador, determina los códigos. Las brechas basadas en dimensiones no fiables son artefactos de la rúbrica.

1. Muestra. Toma aleatoriamente el 10 % del corpus, mínimo 10 elementos, con una semilla fija: python recode_check.py sample --items items.csv --config config.json --out recode_sheet.csv --keep link La hoja contiene solo el ID del elemento y el enlace, con columnas de dimensión vacías.
2. Segundo codificador, ciego. Una persona diferente, o una sesión de agente separada que nunca ha visto los primeros códigos (sin acceso a items.csv, los clústeres o el informe), codifica la hoja usando solo la rúbrica escrita y las páginas públicas del elemento. Si el mismo agente debe hacerlo, inicia un contexto nuevo y dale solo la hoja y la rúbrica. Bloquea el resultado antes de comparar (ej. almacena un checksum).
3. Acuerdo por dimensión: python recode_check.py agree --items items.csv --config config.json --recode recode_sheet.csv --out agreement.csv
   • Dimensiones categóricas: kappa de Cohen (κ).
   • Dimensiones ordinales: kappa de Cohen ponderado linealmente (κw), que da crédito parcial por casi aciertos.
   • El porcentaje de acuerdo bruto se informa junto con una lista de desacuerdos por elemento.
4. Umbral. Una dimensión pasa con κ (o κw) ≥ 0.60 y acuerdo bruto ≥ 80 %. Con n ≈ 10 kappa es ruidoso: úsalo para triaje, y lee cada desacuerdo.
5. Por debajo del umbral, en este orden:
   1. Lee los desacuerdos y clasifícalos: ambigüedad de la rúbrica (valores superpuestos, ancla no medible), confusión entre representación y estructura, o error del codificador.
   2. Arregla la rúbrica con una de las reglas de decisión del paso 2.3 (orden de precedencia, ancla medible, fusiona valores que no se puedan distinguir).
   3. Recodifica esa dimensión para todo el corpus con la rúbrica revisada, luego vuelve a ejecutar la verificación en una muestra fresca del 10 % (nueva semilla) para esa dimensión.
   4. Si aún falla: reduce su peso (≤ 0.6), elimínala de gap_dims, o elimínala. Nunca informes una brecha cuyo triple explicativo se base en una dimensión que falló dos veces.
6. Informa la tabla (dimensión, n, % acuerdo, κ/κw, estado), los cambios en la rúbrica realizados y el tipo de identidad del segundo codificador (humano, agente separado).

Resultado típico: las dimensiones sobre función (acción, objetivo, entrada/salida, desencadenante) concuerdan bien; las dimensiones perceptuales o estimadas (estilo, estructura espacial, duración) son los fallos habituales, razón por la cual existen las reglas de decisión del paso 2.3.

3. Espacio: codificación, clústeres, gradientes y visualización

Lo realiza niche_core.py. Regla de oro: los clústeres y las brechas se calculan en el espacio codificado original; UMAP es solo para dibujar.

• Codificación. One-hot × peso/√2 para dimensiones categóricas y (x − min)/(max − min) para ordinales, de modo que cambiar de categoría cueste lo mismo que un movimiento ordinal de extremo a extremo.
• Clústeres. Ward aglomerativo con k elegido por silueta dentro de k_range. Se acepta un k más grande solo si mejora la silueta en más de 0.005.
  • Verificación de rango k: si el k elegido cae en cualquier extremo del rango, amplía el rango y vuelve a ejecutar; el script advierte. Si permanece en el extremo, elige k por interpretabilidad y dilo.
  • La silueta entre 0.15 y 0.30 es normal con datos categóricos; no lo vendas como "clústeres nítidos".
  • Los clústeres con < 3 elementos y los elementos con vectores idénticos se marcan; estos últimos sugieren una rúbrica demasiado gruesa para distinguir elementos.
  • Nombra cada clúster manualmente a partir de cluster_profiles.md y almacena los nombres en cluster_names.
• Gradientes. Las cargas de PCA (PC1-PC3, pca_loadings.csv) se leen como ejes "de A a B".
• Visualización. UMAP (n_neighbors 10-15, min_dist 0.25, semilla fija) con un fondo de densidad KDE. Limitaciones:
  • las distancias globales y los tamaños de las islas no significan nada;
  • transform tiende a llevar nuevos puntos a la isla más cercana, por lo que la novedad de un candidato se lee desde dist_min en el espacio original, nunca desde el gráfico.
• Mapas de calor por pares de dimensiones muestran celdas vacías de un vistazo.

4. Brechas

4a. Brechas combinatorias (triples). Para cada triple de valores de las dimensiones de brecha (concepto), compara lo observado con lo esperado bajo independencia: e = N · p(a) · p(b) · p(c), z = (e − o)/√e. Se conserva un triple si:

• o ≤ max_observed (por defecto 1);
• e ≥ min_expected (por defecto 1.2);
• cada par del triple aparece en al menos min_pair_support elementos (por defecto 2): las piezas existen por separado;
• toca al menos una dimensión ancla (anchor_dims, ej. dominio o verbo).

Filtro de meta-brecha: mantén las dimensiones de atributo fuera de gap_dims, y establece anchor_dims en las dimensiones que describen el contenido del producto. Los triples hechos solo de atributos no son nichos.

4b. Brechas de densidad. Se generan 50,000-400,000 vectores sintéticos aleatorios y se conservan solo si:

1. cada par de valores existe en al menos un elemento real (recombinación de piezas conocidas);
2. ninguna regla de coherencia los prohíbe (rules: combinaciones absurdas en el dominio);
3. coinciden con el perfil de usuario objetivo (target_filter, ej. complejidad ≤ 1 y autoservicio = 1). Este es el filtro de ajuste de usuario: sin él, las brechas de densidad se desvían hacia productos que el usuario no puede construir o vender.

Los supervivientes se clasifican por distancia al elemento real más cercano y se desduplican en las dimensiones conceptuales principales (density_dedupe). Compara con la distancia mediana al vecino más cercano entre elementos reales distintos (median_nn_distance).

4c. Oferta vs demanda (opcional). Por clúster: número de elementos (oferta) vs la mediana de una señal de demanda (reseñas, instalaciones, volumen de búsqueda, estrellas), siempre con su cobertura (supply_demand_clusters.csv). Un clúster pequeño con alta demanda es una pista de brecha (inferencia).

4d. Puntuación preliminar. Novedad (1-5, de la distancia relativa y el triple que explica la brecha), viabilidad (1-5, esfuerzo de MVP con los recursos del usuario) y ajuste (1-5, preferencias y restricciones del paso 0). Para cada candidato, verifica sus 3 vecinos más cercanos añadiéndolo a candidates y volviendo a ejecutar.

5. Traducción semántica: del vector a la idea

Elige de 8 a 12 candidatos de los triples con z más alta y las brechas de densidad más lejanas; fusiona señales y elimina duplicados. Cada candidato recibe:

• Nombre de trabajo y un discurso concreto de 2-3 oraciones: qué hace el usuario, qué entrega el producto.
• Vector en todas las dimensiones; debe satisfacer las reglas.
• Elementos más cercanos con distancia (× mediana).
• Por qué parece vacío en el corpus: qué triple o zona lo explica, y si alguna de sus dimensiones falló en el paso 2b.
• Riesgos: técnicos, de mercado y de ajuste.

6. Validación externa y prueba de espejismo

1. Búsqueda dirigida por candidato, fuera del corpus:

   • "[concepto] + app/herramienta + precios";
   • "[concepto] alternativa";
   • tiendas del dominio con 2-3 sinónimos;
   • repositorios de código abierto.

   Registra 3-5 competidores con enlace y precio. Asume que casi siempre aparecerá alguno: un corpus de N ≈ 100 no cubre la larga cola. Ajusta la novedad en consecuencia.

2. Prueba de espejismo (adaptada de white-space-analysis, ver Referencias). El candidato enfrenta cuatro preguntas:

   • Tamaño: ¿hay suficientes personas con este trabajo por hacer?
   • Disposición a pagar o cambiar: desde la evidencia más sólida a la más débil, ya pagan por una solución parcial, mantienen una costosa solución alternativa, o intentaron construirla ellos mismos.
   • Pregunta del incumbente: ¿por qué nadie lo ha llenado? Respuestas aceptables: conflicto de modelo de negocio o canal, un cambio externo reciente, un segmento creciente. Respuesta alarmante: "No encuentro una razón".
   • Capacidad de ganar: ¿puede el usuario objetivo superar la barrera que mantiene vacía la brecha?

   Veredicto: pasa (factor 1.0), dudoso (0.7) o falla (0.4).

3. Puntuación final = novedad × viabilidad × ajuste × factor de espejismo (rango 0.4-125).

4. Los candidatos que fallan en la validación permanecen en el informe como "brechas falsas". Exponen el sesgo del corpus y...

[truncado para traducción]