alirezarezvani/claude-skills

Dossier — Investigación de Entidades de Grado Decisional

Portabilidad: Requiere WebSearch + WebFetch, Node.js con el paquete docx y, opcionalmente, bash_tool + curl para APIs gratuitas (SEC EDGAR, GitHub, ProPublica). Los MCPs BYOK (LinkedIn, Crunchbase, Apollo, Pitchbook, SimilarWeb) son mejoras opcionales. Funciona de forma nativa en Claude Code CLI.

Marco No Genérico — El Diferenciador

Esta habilidad es una investigación de entidades de grado decisional con prueba de hipótesis. Se niega a ser "cuéntame sobre Microsoft". Cada invocación obliga al usuario a exponer su hipótesis por adelantado (P4) para que el dossier la ponga a prueba en lugar de confirmarla.

La forma del caso de uso:

"Tengo una presentación con Microsoft el martes. Mi hipótesis es que están consolidando el gasto en IA en su plataforma Foundry de primera parte. Valida o refuta, y dame tres temas de conversación vinculados a lo que encuentres."

NO:

"Cuéntame sobre Microsoft."

La pregunta forzosa P4 — la hipótesis — es el ancla no genérica. Sáltala y la habilidad produce un resumen de Wikipedia.

Consulta references/hypothesis_testing_discipline.md para el canon.

Reglas de Integridad del Agente (Convención de Research-Pack)

Bloqueadas textualmente según auditoría PR #657.

• Disciplina de ejecución. Llamadas de búsqueda secuenciales. WebSearch + WebFetch tienen límites de velocidad más flexibles que Consensus, pero aún se aplica la etiqueta de 1 consulta/segundo. Confirma la recepción de la respuesta antes de la siguiente llamada.
• Disciplina de fuentes. Cita solo fuentes devueltas por las llamadas a herramientas de esta sesión. Wikipedia / conocimiento de entrenamiento etiquetado como [Background — verify before quoting] y excluido del recuento de hallazgos principales.
• Seguimiento de tres recuentos. Consultas enviadas / fuentes recibidas / fuentes citadas. Además, desglose por nivel (primario / secundario / terciario) único para el dossier. Se muestra en el registro de auditoría.
• Política de reintentos. Si falla → espera 3 s → reintenta una vez → registra. Después de 3 fallos consecutivos: detente, alerta al usuario.
• Nivel de fiabilidad de la fuente. Cada cita etiquetada como primaria (oficial, SEC, registros judiciales) / secundaria (noticias principales, prensa especializada) / terciaria (blogs, foros). El DOCX muestra el nivel en cada indicador.

Fase 1: Toma de Datos Forzosa (6 preguntas, una a la vez)

P1 (raíz) — Identidad del sujeto

¿Quién es el sujeto? Dame el nombre exacto y, si es una empresa, el sitio web o URL de LinkedIn. Si es una persona, su URL de LinkedIn o un identificador único (afiliación a empresa + cargo).

Por qué pregunto: Desambiguación. Hay 47 Juan Pérez. Hay tres empresas llamadas "Atlas". Necesito una entidad específica para investigar.

Si el usuario da solo un nombre, insiste por un segundo identificador. No continúes con nombres ambiguos.

P2 (depende de P1) — Tipo de sujeto

¿Qué tipo de sujeto es? Elige uno: persona / empresa / organización sin fines de lucro / entidad gubernamental / otro.

Por qué pregunto: Se aplican diferentes matrices de fuentes. Para personas reviso LinkedIn, GitHub, Scholar, noticias; para empresas reviso SEC EDGAR (si es pública), Crunchbase, noticias, GitHub para organizaciones tecnológicas; para organizaciones sin fines de lucro reviso Formularios 990 en ProPublica.

Elección forzosa. "Otro" requiere una descripción de una línea.

P3 (depende de P2) — Propósito

¿Para qué te estás preparando? Elige uno:

1. Reunión de ventas / presentación de sociedad
2. Diligencia de inversión
3. Diligencia de adquisición
4. Periodismo / debida diligencia
5. Preparación para entrevista de trabajo
6. Inteligencia competitiva
7. Verificación personal (cita, contratación, socio comercial)
8. Otro (especifica)

Por qué pregunto: El propósito dicta el ángulo, la profundidad y la sensibilidad de las banderas rojas. La preparación de ventas necesita temas de conversación. La diligencia de inversión necesita señales de tracción. La verificación personal necesita límites de sensibilidad cuidadosos.

P4 (depende de P3) — Hipótesis — OBLIGATORIA

¿Cuál es tu hipótesis inicial? ¿Qué es lo que ya crees sobre este sujeto y qué quieres verificar o refutar?

Por qué pregunto: Esta es la pregunta crítica. Un dossier que solo confirma lo que ya piensas no tiene valor. Al declarar tu hipótesis por adelantado, puedo buscar evidencia que la refute además de evidencia que la respalde, y darte un veredicto que realmente puedas usar.

Ejemplos:

• "Creo que Microsoft está consolidando el gasto en IA en Foundry de primera parte. Verifica o refuta."
• "Creo que el CEO está fuera de su alcance — mucho hablar de TAM, nada de tracción. Ponlo a prueba."
• "Creo que la proporción de gastos generales de esta organización sin fines de lucro es sospechosa. Revisa los 990."
• "Creo que esta persona es lo suficientemente técnica como para asumir un rol de CTO. Verifica."

OBLIGATORIA. Si el usuario dice "no tengo una", insiste una vez: "Entonces adivina. Comprométete con una posición que puedas actualizar después. El dossier necesita una hipótesis que probar; de lo contrario, es un perfil genérico y no te ayudará a tomar una decisión."

Si aún se niega: recurre a la hipótesis implícita "¿cuál es lo más sorprendente que podría encontrar?" y marca la alternativa en el registro de auditoría.

Esta pregunta es el ancla no genérica. Sáltala y la habilidad se convierte en un resumen de Wikipedia.

P5 (depende de P3) — Profundidad

Horizonte temporal: ¿informe breve de 5 minutos o dossier de grado decisional de 15 minutos?

Por qué pregunto: El modo breve limita a ~10 búsquedas y omite los pases de red y reputación. El modo de grado decisional profundiza en cada sección. Elige según cuánto esté en juego en esta decisión.

Elección forzosa.

P6 (solo si P3 ∈ {periodismo, verificación personal}) — Sensibilidades

¿Hay algo sensible que excluir? Por ejemplo, datos médicos personales, detalles familiares, historial político o temas específicos prohibidos?

Por qué pregunto: Algunos contextos de investigación tienen restricciones éticas. Prefiero saberlo de antemano que sacar a la luz algo que nunca compartirías.

Omitir para ventas/inversión/adquisición/inteligencia competitiva (baja sensibilidad); preguntar para periodismo/verificación personal (alta sensibilidad).

Condición de parada: Después de P6 (o antes con omisiones por dependencia), comprométete e inicia la Fase 2. Nunca reabras la toma de datos después de que comience la Fase 2.

Fase 2: Desambiguación del Sujeto

Antes de la Fase 3, resuelve el sujeto a una entidad específica:

• Para personas: confirma URL de LinkedIn O (empleador + cargo + ciudad)
• Para empresas: confirma dominio O (nombre legal + jurisdicción de constitución)
• Para organizaciones sin fines de lucro: confirma EIN O (nombre legal + estado)
• Para entidades gubernamentales: confirma URL oficial .gov

Si aún es ambiguo después de la insistencia de P1: detente y vuelve a preguntar P1 con identificadores desambiguadores. No continúes.

Fase 3: Selección de la Matriz de Fuentes

Enrutada por el tipo de sujeto de P2. Consulta references/subject_type_source_matrix.md para el canon completo.

Persona

• LinkedIn (obtención manual o MCP de LinkedIn si BYOK)
• Sitio web personal
• Twitter/X (con límite de velocidad; degrada con elegancia)
• GitHub (si el sujeto es técnico)
• Google Scholar (si es académico)
• Noticias (WebSearch + WebFetch)
• Transcripciones de conferencias, podcasts (WebSearch)

Empresa

• Sitio web oficial (acerca de, liderazgo, noticias, carreras)
• SEC EDGAR (API gratuita; 10-Ks, 10-Qs, 8-Ks para empresas públicas)
• Nivel gratuito de Crunchbase (o MCP de Crunchbase si BYOK)
• Noticias (WebSearch + WebFetch)
• GitHub (para organizaciones tecnológicas)
• Glassdoor + Comparably (sentimiento; degrada con elegancia si el scraping está bloqueado)
• Página de LinkedIn de la empresa

Organización sin fines de lucro

• ProPublica Nonprofit Explorer (gratuito; Formularios 990)
• Sitio web oficial
• Noticias
• GuideStar (si es accesible)

Entidad gubernamental

• Sitios oficiales .gov
• Noticias
• ProPublica (para agencias federales)

Si un MCP de pago está conectado (Apollo, Pitchbook, SimilarWeb), úsalo pero marca los hallazgos como BYOK-sourced en el registro de auditoría.

Fase 4: Búsqueda Dirigida por Hipótesis

Cada búsqueda de la Fase 4 DEBE clasificarse como:

• Evidencia de apoyo (confirma la hipótesis), O
• Evidencia contradictoria (refutaría la hipótesis)

≥30% del presupuesto de búsqueda asignado a consultas contradictorias. Aplicado mediante scripts/disconfirming_evidence_balance.py.

Ejemplo para la hipótesis "Microsoft está consolidando el gasto en IA en Foundry":

• Apoyo: "adopción de Microsoft Foundry 2026", "consolidación de infraestructura de IA de Microsoft"
• Contradictorio: "renegociación del acuerdo Microsoft-OpenAI", "diversificación de proveedores de IA de Microsoft", "asociaciones de modelos de terceros de Microsoft 2026"

Esto es lo que hace que el dossier sea de grado decisional en lugar de tener sesgo de confirmación.

Para cada búsqueda:

• Registra mediante citation_tracker.py con clasificación (apoyo / contradictorio)
• Aplica el nivel de fuente desde source_tier_classifier.py a cada URL de resultado

Fase 5: Línea de Tiempo de Actividad de 12 Meses

Ventana predeterminada de 12 meses para la línea de tiempo de actividad; más profunda para la identidad fundacional.

Categorías:

• Noticias (adquisiciones, contrataciones, salidas, lanzamientos de productos)
• Rondas de financiación / eventos financieros
• Controversias / eventos legales
• Declaraciones públicas / cambios de estrategia

Orden cronológico inverso. Cada entrada con hipervínculo y nivel.

Fase 6: Señales de Red + Reputación

Red

• Empresas: inversores (entrada/salida), clientes (mencionados), socios
• Personas: cofundadores, asesores, mentores, empleadores, roles en juntas directivas
• Organizaciones sin fines de lucro: financiadores, junta directiva, liderazgo

5-10 entradas, clasificadas por relevancia para la hipótesis.

Reputación

• Sentimiento de noticias (últimos 12 meses)
• Glassdoor para empresas (calificación general + 3 reseñas representativas)
• Menciones de pares para personas
• Advertencia: los datos de reputación son ruidosos; clasifica en consecuencia

Fase 7: Pase de Banderas Rojas

Muestra pero no sensacionalices:

• Litigios (registros judiciales → nivel primario)
• Acciones regulatorias (SEC, DOJ, acciones de agencias → primario)
• Salidas inusuales (salidas de personal clave en 90 días)
• Señales financieras (notas de empresa en funcionamiento en 10-Ks → primario)
• Impactos reputacionales (cobertura negativa sostenida → secundario)

Cada indicador con nivel. El nivel aparece junto a cada indicador en el DOCX.

Fase 8: Generación de Temas de Conversación

3-5 temas específicos vinculados a hallazgos reales, no puntos de conversación genéricos.

Consulta references/conversation_hook_quality.md para el canon.

❌ Genérico	✅ Vinculado a hallazgo
"Pregunta sobre su hoja de ruta"	"Menciona su reciente adquisición de [X] — indica que están invirtiendo en la vertical Y. Marco sugerido: 'Vi el anuncio de [X] — ¿cómo cambia eso tu hoja de ruta en Y?'"
"Pregunta sobre contrataciones"	"Su VP de Ingeniería se fue hace 3 semanas (LinkedIn). Marco sugerido: 'Noté que [nombre] se fue — ¿cuál es el plan de liderazgo técnico?'"
"Habla sobre sus valores"	"Actualizaron su página de precios la semana pasada (su sitio oficial). Marco sugerido: 'Vi la actualización de precios — ¿qué la motivó?'"

Cada tema:

• El tema (una oración)
• El hallazgo al que está vinculado (con hipervínculo + nivel)
• Marco sugerido (redacción textual que el usuario puede adaptar)

Fase 9: Generación de DOCX (9 Secciones)

Mediante Node.js + librería docx.

1. Resumen Ejecutivo — un párrafo: quiénes son + por qué importan + veredicto sobre la hipótesis (RESPALDADA / RESPALDADA PARCIALMENTE / REFUTADA / NO CONCLUYENTE) + 3 viñetas de cosas que debes saber.
2. Tabla de Datos de Identidad — fundado/nacido, ubicación, tamaño/etapa, rol actual, afiliaciones clave. Todas las celdas con fuente; texto flotante con nivel.
3. Prueba de Hipótesis — hipótesis del usuario citada textualmente. Evidencia de apoyo (3-5 viñetas con citas con hipervínculo). Evidencia contradictoria (3-5 viñetas con citas con hipervínculo). Párrafo de veredicto (2-3 oraciones explicando el peso).
4. Línea de Tiempo de Actividad de 12 Meses — Noticias, financiación, contrataciones, salidas, lanzamientos de productos, controversias. Orden cronológico inverso. Cada entrada con hipervínculo.
5. Señales de Red — Colaboradores / inversores / asociados. 5-10 entradas, clasificadas por relevancia para la hipótesis.
6. Señales de Reputación — Sentimiento de noticias, Glassdoor para empresas, menciones de pares para personas. Advertencia: los datos de reputación son ruidosos.
7. Banderas Rojas + Patrones Ocultos — Litigios, acciones regulatorias, salidas inusuales, señales financieras, impactos reputacionales. Con niveles.
8. Temas de Conversación — 3-5 temas específicos vinculados a hallazgos. Cada uno: tema + hallazgo + marco sugerido.
9. Procedencia de Fuentes + Registro de Auditoría — Lista por fuente con nivel. Tabla de resumen de búsquedas (#, consulta, clasificación, fuentes devueltas, fuentes citadas). Tres recuentos + recuentos por nivel. Búsquedas fallidas. Indicador de uso de MCP BYOK.

Estilo

Cuerpo Arial 12pt, títulos azul marino (#1a3a5c), encabezados de tabla azul claro (#e8f0f8), llamada de bandera roja en rojo, llamada de tema de conversación en verde.

Patrones de hipervínculo

new ExternalHyperlink({
  link: "https://...",
  children: [new TextRun({ text: title, style: "Hyperlink" })],
});

Fase 10: Entrega

• Guardar: <output-dir>/dossier_<entity-slug>_<YYYY-MM-DD>.docx
• Resumen en chat: ruta del archivo + veredicto sobre la hipótesis + recuentos de auditoría + desglose por nivel + MCPs BYOK utilizados (si los hay)
• Validar: verifica la integridad del zip con python3 -c "import zipfile,sys; zipfile.ZipFile(sys.argv[1]).testzip()" <docx> (sin salida = intacto), luego confirma que las secciones requeridas están presentes

Herramientas

Script	Rol
scripts/citation_tracker.py	Auditoría de tres recuentos + clasificación apoyo/contradictorio + etiquetado de nivel de fuente en ~/.dossier_sessions/<session>.json
scripts/disconfirming_evidence_balance.py	Verifica que ≥30% del presupuesto de búsqueda se asigne a consultas contradictorias; advierte si hay sesgo
scripts/source_tier_classifier.py	URL → clasificación primaria / secundaria / terciaria mediante heurísticas de dominio

Referencias

• references/hypothesis_testing_discipline.md — regla ≥30% + grado decisional vs enciclopédico (7+ fuentes)
• references/subject_type_source_matrix.md — matrices de fuentes para persona/empresa/org sin fines de lucro/gobierno (7+ fuentes)
• references/conversation_hook_quality.md — disciplina de temas vinculados a hallazgos (7+ fuentes)

Manejo de Errores

Fallo	Comportamiento
Nombre del sujeto ambiguo	No continúes. Vuelve a preguntar P1 con un identificador desambiguador.
El usuario se niega a declarar una hipótesis	Insiste una vez. Si aún se niega, recurre a la hipótesis implícita "¿cuál es lo más sorprendente que podría encontrar?". Márcalo en la auditoría.
El sujeto tiene cero presencia pública	Registra en auditoría. Genera dossier parcial con sección "No se encontraron fuentes primarias". Elige hipótesis por entender.
API gratuita o MCP agota cuota	Degrada con elegancia. Continúa con fuentes restantes. Registra "Fuente no disponible" en auditoría.
Extremo tras extremo de conversación credencial	Espera 1 s entre llamadas. Respeta límites de velocidad.

Estructura de Directorios

scripts/
├── citation_tracker.py
├── disconfirming_evidence_balance.py
└── source_tier_classifier.py

references/
├── hypothesis_testing_discipline.md
├── subject_type_source_matrix.md
└── conversation_hook_quality.md

Integración

1. Clona este repositorio o copia la estructura en tu entorno de trabajo.
2. Instala dependencias: npm install docx (Node.js) y asegúrate de que Python 3 esté disponible para los scripts.
3. Opcional: conecta MCPs BYOK para fuentes adicionales.
4. Invoca esta habilidad en tu agente de IA (por ejemplo, Claude Code) y pasa por el proceso de 6 preguntas.

---

Habilidad de grado decisional para análisis informado. No sustituye el asesoramiento profesional.